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内 容 提 要 


本 书 一 宕 GitHub 内 部 使 用 的 工具 ， 以 叙事 的 方式 描述 构建 软件 元 工具 的 相关 过 程 ， 甚 中 不 











只 介绍 相关 的 技术 ， 还 会 说 明 折 中 方案 、 重 构 的 现实 意义 ， 以 及 编写 元 工具 所 面临 的 挑战 。 对 已 








经 熟悉 Git 或 GitHub、 想 提升 相关 技能 的 读者 ， 书 中 介绍 了 如 何 使 用 GitHub API 及 相关 的 开源 技 
术 ， 如 Jekyll (网 站 生成 工具 )、Hubot (NodeJS 聊天 机 器 人 ) 和 Gollum (维基 ) 构建 工具 。 
本 书 适合 所 有 想 要 使 用 GitHub 进行 开发 的 程序 员 。 
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O'Reilly Media, Inc. 介 绍 


O'"Reilly Media 通过 图 书 、 杂 志 、 在 线 服 务 、 调 查 研究 和 会 议 等 方式 传播 创新 知识 。 
自 1978 年 开始 ，O’Reilly 一 直 都 是 前 沿 发 展 的 见证 者 和 推动 者 。 超 级 极 客 们 正在 开创 
着 未 来 ， 而 我 们 关注 真正 重要 的 技术 趋势 一 一 通过 放大 那些 “细微 的 信号 ”来 刺激 社 
会 对 新 科技 的 应 用 。 作 为 技术 社区 中 活跃 的 参与 者 ，O’Reilly 的 发 展 充满 了 对 创新 的 
倡导 、 创 造 和 发 扬 光 大 。 


O’Reilly 为 软件 开发 人 员 带 来 革命 性 的 “动物 书 ”， 创 建 第 一 个 商业 网 站 (GNN) ; 组 
织 了 影响 深远 的 开放 源 代码 峰会 ， 以 至 于 开源 软件 运动 以 此 命名 ;创立 了 Make 杂志 ， 
从 而 成 为 DIY 革命 的 主要 先锋 ， 公 司 一 如 既往 地 通过 多 种 形式 缔结 信息 与 人 的 纽带 。 
O’Reilly 的 会 议和 峰会 集聚 了 众多 超级 极 客 和 高 瞻 远 瞩 的 商业 领袖 ， 共 同 描绘 出 开创 
新 产业 的 革命 性 思想 。 作 为 技术 人 士 获 取信 息 的 选择 ，O’Reilly 现在 还 将 先锋 专家 的 
知识 传递 给 普通 的 计算 机 用 户 。 无 论 是 通过 书籍 出 版 、 在 线 服务 或 者 面授 课程 ， 每 一 















































项 O'Reilly 的 产品 都 反映 了 公司 不 可 动摇 的 理念 一 一 信息 是 激发 创新 的 力量 。 
业界 评论 
“O'"Reilly Radar 博客 有 口 党 碑 。” 





Wired 


“O’Reilly 凭借 一 系列 (真希 望 当 初 我 也 想到 了 ) 非凡 想法 建立 了 数 百 万 美元 的 业务 。” 


Business 2.0 





“O'Reilly Conference 是 聚集 关键 思想 领袖 的 绝对 典范 。” 
一 一 CRN 


“一 本 O'Reilly 的 书 就 代表 一 个 有 用 、 有 前 途 、 需 要 学 习 的 主题 。 


Trish Times 





“Tim 是 位 特 立 独行 的 商人 ， 他 不 光 放 眼 于 最 长 远 、 最 广阔 的 视野 ， 并 且 切 实地 按照 
Yogi Berra 的 建议 去 做 了 : “如果 你 在 路 上 遇 到 岔路 口 ， 走 小 路 ( 岔路 ), ”回顾 过 去 ， 
Tim 似乎 每 一 次 都 选择 了 小 路 ， 而 且 有 几 次 都 是 一 闪 即 逝 的 机 会 ， 尽 管 大 路 也 不 错 。 


Linux Journal 




















1 言 do eas esl eb eed a xi 
第 1 章 开放 的 GitHub APleeeee 1 
URI 1 
12 列举 API 路 答 2 
1.3 JSON 格式 de dd ede a da 
1.3.1 在 命令 行 中 解析 JSON 
1.3.2 ”cURL 的 调试 开 美 和 
es I A 
1.5 跟随 超 媒体 API 
1.6 身份 验证 人 
1.6.1 用 户 名 和 密码 验证 Ne 7 
下 人 四 六 各 仙人 8 
1.7 4| 态 码 SA 10 
1.7.1 成 功 (200 或 202 ee 10 
1.7.2 不 合 规 的 JSON (400 ee 10 
1.7.3 ”错误 的 JSON (422 ee 11 
1.7.4 ”成功 创建 (201 ee 12 
1.7.5 ”完全 没 变 化 (304 ee 12 
1.7.6 GitHub API 的 频率 限制 12 
1.7.7 获知 频率 限制 ed ode a ea 13 
:8 使 用 条 件 请 求 规避 频率 限制 i dd en a 14 
1.9 在 Web 中 访问 内 容 





1.9.1 JSON-P oo 和 


1.9.2 ”CORS 支持 16 
1.9.3 指定 响应 的 内 容 格式 生 | 





1.10 小结 








第 2 章 Gist 和 Gist AP 19 
2.1 简便 的 代码 分 享 工具 SR i RR A 19 
2.2 ”Gist 是 仓库 20 

2.2.1 在 HTML 中 奉 入 GiSt 21 

99012 让.Jekyll 博 容 中 洪 入 加 boi 21 
2.3 ”使 用 命令 行 创建 Gist ee 21 
2.4 ”Gist 是 功能 完整 的 应 用 22 
28 “入 六 :Glot 的 "GiBE eon 捕 的 生生 全 23 

2.5.1 深入 了 解 Gist AP 


2.5.2 ”使 用 Octokit 获取 超 媒 体 数 据 
2.6 小 结 VAD A A A A 





























第 3 章 GitHub 使 用 的 维基 库 GolluM 28 
ee 六 
3.1.1 与 仓库 关联 的 维基 pe 29 
3.1.2 ”标记 和 结构 ee 30 
3.2 ”改造 GollQmee 33 
53- 并 始 创 建 Gollum 缠 辑 吕 0 时 oo 34 
于 “以 编程 的 方式 妈 理 图 像 :0 和 ore 34 
3.5 使 用 Rugged 库 ee ee ee ee a 36 
3.6 优化 图 像 存储 
37 一 在 Gitfiib 币 查 看 41 
38 设 管 修订 版 本 时 般 于 讨 eo 43 
3.9 ”修缮 素材 页 面 之 间 的 链接 ………………… 44 
3.10 小 结 i 45 
第 4 章 Python 和 Search APleeeee 46 
二 SEE 有 站 den 
4.1.1 身份 验证 
4.1.2 结果 的 格式 和 47 
直人 - 靶 过 运 千 逢 和 限定 蔡司 48 


4.1.4 排序 
4.2 Search API 详解 i aD a ed a ee en a ae a en ei oa sn 49 








vi | 目录 


4.3 
4.4 


4.2.1 搜索 仓库 49 
4.2.2 ”搜索 代码 ee 50 
4.2.3 ”搜索 工 间 人 51 
4.2.4 ”搜索 用 户 eeee 52 





ACEI OD ae 
4.4.2 WxPython 
4.4.3 PylInstaller 

















4 57 
4.5.1 获取 Git 赁 据 的 辅助 画 数 和 58 
4.5.2 口 和 界面 和 59 
4.5.3 登录 GitHub 62 
4.5.4 搜索 GitHub ee 65 
4.5.5 ”显示 结果 esses 67 
4.6 打包 ROP OO EO ET RR RT RR 68 
4.7 ”小结 69 
第 5 章 .NET 和 Commit Status AP 70 
ST TOMmitort AD 
S11 过 类 状 坟 i 
5.1.2 合并 后 的 状 想 和 yp) 
5.1.3 创建 状态 Sd dd 73 
S99- 纺 容 二 3 个 作用 74 
52T 委 使 用 交 库 no i 74 
5.2.2 开发 环境 和 74 
S.2.3 发送 请 来 和 77 
350d OND 证 沪 站 N 79 
5.2.5 处 理 状态 的 画 数 83 
5.3 小 结 a om ne a a 84 
第 6 章 Ruby 和 Jekyll ee dy 86 
6.1 学 习 使 用 Jekyll 构建 博客 和 86 
6.2 Jekyll 是 什 各 和 86 
6.3 使 用 Jekyll 快速 创建 博客 ee 88 
6.3.1 YAML 格式 的 头 部 元 信息 和 91 
6.3.2 Jekyll 使 用 的 标记 区 ee 92 








6.3.3 使 用 Jekyll 命令 Sd 93 






























et ep a 93 
全 3 和 “Fe 93 
6.3.6 ”发布 到 GitHub 中 93 
6.3.7 托管 在 自己 的 域名 名 下 ee 94 
6.4 导入 其 他 博客 “96 
6.4.1 导入 WordPregsgs 96 
6.4.2 从 其 他 博客 中 时 入 97 
6.3 不 取 网 站 ， 导 入 Jekyl ee 98 
6.5.1 慌 取 策略 98 
6.5.2 设置 站 
6.5.3” 疏 取 标题 
6.5.4 借助 交互 式 Ruby 控制 台 改 善 二 
6.5.5 编写 测试 ， 处 理 缓存 和 103 
6.5.6 输出 Jekyll 文章 和 108 
6.5.7 使 用 jekyll 命令 行 工 具 和 ee 110 
6.$.8 使 用 Liquid Markup 编写 主 索引 文件 和 112 
6.$.9” 慌 取 正文 和 作者 114 
6.5.10 ”把 图 像 添加 到 Jekyll 中 115 
6.5.11 自 定 义 样式 ( CSS ) 116 
6.5.12 通过 GitHub 的 “派生 ”功能 鼓励 协作 Ne 118 
6.$.13 ”把 博客 发 布 到 GitHub 中 119 
C6 1 | 生 全 全 生生 让 生生 119 
第 7 章 Android 和 Git Data AP 120 
7.1 搭建 环境 
7.1.1 创建 Jekyll 博客 
到 2， ndioid 江 发 二 下 121 
7.2 新 建 项 目 121 
7.2.1 编辑 Gradle 构建 文件 
7.2.2 Android 默认 的 主 活 动 
7.3 自动 测试 Android 应 用 
7.3.1 对 GitHub 客户 端 做 单元 测试 
7.3.2 ”对 Android 应 用 做 UT 测试 和 
7.4 实现 应用 .ee 和 ee 作 人 nn nnnnnnnnnnnnnnnnnnnnnnnonnneosnneesns 
了 直下 区 号 登 亲 GitEub 的 并 De 136 
了 十 2 < 区 全 与:GitHip 放 这 的 代 状 呈 有 全 王 天语 二 址 各 刘 的 向 的 拓 交 放 起 二 区 140 





viii 








目录 








7.4.3 ”编写 博客 内 容 





























7.4.4” ”GitHub 服务 和 
F745 众 在 连 和 分 支 市 装 取 荐 轩 人 生生 全 aaa 144 
7.4.6 ”创建 blob ee 145 
7.4.7 生成 树 145 
7.4.8 ”创建 提交 146 
7.4.9 更 新 上 游资 源 和 147 
7.4.10 ”通过 全 部 测试 147 

7.5 小 缚 和 149 

第 8 章 CoffeeScript、 Hubot 和 Activity APlee 150 

8.1 Activity API 

8.2 让 拉 取 请 求 得 到 各 方 认同 Si A nd et CP 151 
8.2.1 注意 事项 和 局 限 和 151 
8.2.2 ”创建 常规 的 Hubot 
8.2.3 注册 Slack 账 户 和 ee 
8.2.4 在 本 地 运行 Hubot 

8.3 部署 到 HerokK nnrnnrnnnn 

8.4 Activity API 概述 Yd A an a tn A nt 
8.4.1 编写 Hubot 扩展 ee 157 
8.4.2 ”通过 拉 取 请 求 审 查 代 而 158 
8.4.3 ”使 用 OAuth 令 牌 注册 事件 163 
8.4.4 发 起 真实 的 拉 取 请 求 站 165 
8.4.5 ”通过 HTTP POST 请 求 处 理 拉 取 请 求 通知 ee 167 

8 Ee ee 187 

第 9 章 JavaScript 和 Git Data APl ee 188 

9.1 构建 一 个 咖啡 店 数据 库 并 托管 在 GitHub 中 

9.2 搭建 环境 PRT TS NO PE TN Ee RCR TO A Te OE RTI A ET RE TA A 
9.2.1 绑 定 域名 
9.2.2 添加 支持 库 

9.3 使 用 GitHub.js 开发 一 个 AngularJS 应 用 191 
9.3.1 规划 应 用 的 数据 结构 PN 193 
9.3.2 ”让 应 用 易于 测试 和 194 
03.3. . 测 江 闭 提 i 198 
9.3.4 修改 coffeetech.js 文件 199 

9.4 添加 地 理 编 码 功 能 











9.5 添加 登录 功能 a nn de dn sd a i dn 203 














96 ' 量 示 节 将 站 淖 府 户 提 代 的 数 所 Ono 205 
9.7 ”接受 拉 取 请 落 ，eee ee ee see nana nannnnnnnnnnnnnnnnnnnnnennennennenns ee。 214 
9.8 ”实现 安全 的 登录 方式 

9.8.1 身份 验证 需要 服务 器 
9.8.2 使 用 Firebase 处 理 身 份 验证 过 程 
9.8.3 测试 FirfebagSe 
9.8.4 实现 Firebase 登录 功能 PN 219 
9.9 ”小结 ee 991 
附录 A GitHub 企业 版 i D9 

附录 B GitHub 对 Ruby、 NodeJS (和 shell) 的 利用 i 226 

作者 简介 TR 232 

关于 封面 CO OTR 232 








到 
ul 


本 书 说 明 如 何 构 建 软件 工具 。 


如 果 你 经 常 编写 软件 ， 肯 定 知道 这 其 实 是 创建 工具 的 过 程 。 软 件 也 是 工具 。 说 到 底 ， 电 子 
表格 只 是 加 减 数 字 的 工具 ， 电 子 游 戏 只 是 打发 无 聊 时 间 的 工具 。 在 人 们 开始 编写 软件 工具 
之 后 ， 我 们 几乎 立即 发 现 ， 为 了 顺利 写 出 一 开始 想 写 的 那个 软件 ， 需 要 有 更 多 的 工具 来 
支持 。 我 们 把 这 些 支持 软件 开发 的 工具 (不 是 常规 意义 上 的 软件 工具 ) 叫 作 元 工具 (meta- 
tool) 。 














在 软件 开发 领域 ， 最 重要 的 一 个 元 工具 是 Git。 这 个 元 工具 能 帮助 软件 开发 者 解决 编写 软 
件 过 程 中 的 复杂 问题 。 使 用 Git， 软 件 开发 者 可 以 存储 程序 的 快照 (如 果 需 要 ， 可 以 轻易 
还 原 快 照 )， 还 便于 与 其 他 程序 员 协 作 (这 是 个 相当 复杂 的 问题 )。Git 是 一 种 源码 管理 
(Source Code Management，SCM) 工具 ， 虽 然 在 此 之 前 有 很 多 SCM 工具 ， 但 是 都 没 像 Git 
这 样 对 软件 领域 产生 如 此 大 的 影响 。 目 前 ，Git 在 SCM 工具 中 处 于 领先 地 位 。 



























































GitHub 公司 及 早 发 现 了 Git 的 无 穷 潜力 ， 以 Git 的 功能 为 底层 基础 ， 构 建 了 一 层 Web 服 
务 。 不 难 想象 ，GitHub 成 功 的 因素 之 一 是 ， 员 工 们 从 一 开始 就 积极 跟随 济济 ， 编 写 大 量 的 
元 工具 。 开 发 元 工具 要 耐 得 住 寂寞 ， 不 能 急于 求 成 。GitHub 的 员工 们 对 这 种 做 事 顺 序 引 以 
为 茉 ， 并 撰写 了 大 量 文章 说 明了 这 样 做 的 好 处 ， 例 如 便于 新 员工 融入 ， 工 作 流 程 对 所 有 员 
工 都 透明 。 


























本 书 一 帘 GitHub 内 部 使 用 的 工具 。GitHub.com 网 站 本 身 也 是 一 个 元 工具 ， 我 们 会 从 多 个 
方面 讨论 GitHub 服务 。 有 具体 而 言 ， 我 们 涉及 的 技术 有 GitHub API 及 相关 的 GitHub 技术 、 
Gollum 维基 、 静 态 页 面 生成 工具 Jekyll， 以 及 聊天 机 器 人 Hubot (如 果 你 对 这 些 都 不 熟悉 ， 
不 用 担心 ， 我 们 将 在 不 同 的 章节 详细 说 明 ) 。 


我 要 重申 一 点 ， 这 不 是 上 述 几 项 技术 的 参考 书 。 这 是 一 本 故事 书 ， 以 叙事 的 方式 描述 构建 
软件 元 工具 的 相关 过 程 ， 期 间 不 只 介绍 相关 的 技术 ， 还 会 说 明 折 中 方案 、 重 构 的 现实 意 
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义 ， 以 及 编写 元 工具 面临 的 挑战 。 


编写 元 工具 所 需 的 思维 与 常规 的 软件 不 同 。 一 般 来 说 ， 元 工具 是 开源 的 ， 用 法 和 责任 都 不 
同 寻常 。 有 人 可 能 认为 ， 与 普通 用 户 相 比 ， 软 件 工程 师 对 质量 有 更 高 的 要 求 ， 因 为 软件 不 
能 满足 软件 开发 者 的 需求 时 ， 他 们 可 以 改进 或 派生 。 编 写 元 工具 需要 付出 更 多 的 精力 ， 攻 
而 自动 化 测试 几乎 是 必 备 的 。 开 发 元 工具 之 前 一 定 要 知道 这 些 概念 ， 本 书 将 告诉 你 如 何在 
构建 元 工具 的 过 程 中 运用 这 些 概念 。 


为 什么 使 用 API， 为 什么 选择 GitHub API 


使 用 API 支持 应 用 是 当下 常见 的 做 法 ， 这 也 是 应 用 开发 的 发 展 方向 。 如 今 显示 设备 多 种 多 
样 ， 使 用 API 能 在 不 同 的 设备 中 更 好 地 呈现 数据 。 以 远程 服务 API 支持 的 应 用 ， 起 初 可 能 
是 运行 在 Apple iOS 操作 系统 中 的 移动 应 用 。 经 市 场 验证 之 后 ， 如 果 发 现 这 种 商业 模式 不 
正确 ， 可 以 迅速 响应 变化 的 需求 ， 为 Android 穿戴 设备 构建 新 应 用 ， 构 建 车 载 应 用 ， 或 者 
其 他 控制 台 (或 非 控制 台 ) 应 用 。 只 要 应 用 能 调用 远程 API 收发 数据 ， 你 就 能 为 任何 平台 
构建 任何 用 户 界 面 。 








































































































此 外 ， 我 们 自己 也 可 以 编写 和 托管 API。Ruby、Go 和 Java 等 流行 语言 的 很 多 框架 都 支持 
使 用 标准 的 架构 风格 (如 REST) 构建 API。 不 想 自己 构建 的 话 ， 还 可 以 使 用 第 三 方 API。 
本 书 专门 针对 一 个 第 三 方 API， 即 GitHub API。 


























为 什么 是 GitHub API 呢 ? 对 构建 软件 的 你 来 说 ， 基 本 上 离 不 开 GitHub API， 因 为 你 可 能 
就 使 用 GitHub 管理 软件 代码 。 即 便 不 用 GitHub， 也 有 可 能 使 用 Git。 而 GitHub API 也 能 
操作 Git， 因 为 它 把 Git 的 功能 抽象 成 网 络 编程 接口 了 。 


GitHub API 算是 我 见 过 设计 得 最 好 的 API 了 。 它 是 超 媒体 API， 基 本 上 成 功 解决 了 一 个 环 
手 问 题 : 让 API 客户 端 适应 API 的 变化 。GitHub API 有 良好 的 版 本 划分 ， 功 能 完整 ， 而 且 
实现 了 大 多 数 Git 功能 。GitHub API 由 多 个 结构 合理 的 部 分 组 成 ， 便 于 构建 应 用 。GitHub 
API 古 个 典型 ， 通 过 它 可 以 学 习 好 的 API 应 该 怎么 设计 。 


本 书 结构 


GitHub API 的 功能 非常 全 面 ， 通 过 它 可 以 访问 和 修改 Git 仓库 中 存储 的 或 与 己 有 关 的 几乎 
所 有 数据 和 元 工具 。 根 据 GitHub API 的 文档 (https://developer.github.com/v3/)， 我 按照 字 
母 顺序 简要 列 出 了 其 各 部 分 的 作用 。 


Activity: 开发 者 关注 的 事件 通知 
Gists: 以 编程 的 方式 创建 和 分 享 代码 片段 
Git Data: 通过 远程 API 访问 原始 的 Git 数据 
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Xii 且 


Dl 


。 JIssues: 添加 和 修改 工 单 

。 Miscellaneous: 无 法 纳入 其 他 分 类 的 API 

。 Organizations: 存 取 组 织 成 员 数 据 

。 Pull Requests: 一 个 强大 的 API， 建 构 在 合并 过 程 之 上 
。 Repositories: 修改 与 仓库 有 关 的 一 切 数 据 

。 Search: 在 整个 GitHub 数据 库 中 搜索 代码 

。 Users: 访问 用 户 数据 

。 Enterprise: 企业 内 部 的 GitHub 专用 的 API 














此 外 ， 有 些 重要 的 技术 在 GitHub API 文档 中 没有 说 明 。 虽 然 这 些 技术 不 是 API 的 一 部 分 ， 
但 是 使 用 GitHub 时 应 该 知道 。 








。 Jekyll 和 “gh-pages”: 托管 博客 和 静态 文档 
。 Gollum: 与 仓库 关联 的 维基 
。 Hubot: GitHub 广泛 使 用 的 可 编程 聊天 机 器 人 





GitHub 技术 栈 的 各 个 部 分 分 别 在 不 同 的 章节 介绍 《有 两 个 不 会 介绍 ， 原 因 如 后 )。GitHub 
APFI 文 档 是 优秀 的 参考 ， 编 写 与 GitHub API 通信 的 应 用 时 会 经 常 查阅 。 本 书 的 目的 则 不 
同 ， 我 们 将 叙述 如 何 使 用 GitHub 提供 的 技术 构建 应 用 。 这 些 故事 会 告诉 你 使 用 GitHub 
API 时 要 采取 哪些 折 中 措施 ， 有 什么 注意 事项 。 如 果 需 要 ， 一 章 可 能 涵盖 多 个 API。 通 常 ， 
每 一 章 都 尽量 专注 于 一 个 主要 的 API， 努 力 不 涉 及 其 他 API， 但 是 大 多 数 章节 确实 需要 涉 
及 别 的 API。 





























下 面 概述 各 章 的 内 容 。 

第 1 章 首次 介绍 如 何 使 用 命令 行 HTTP 客户 端 cURL 访问 API， 并 说 明 响 应 的 格式 、 如 
何在 命令 行 中 解析 响应 ， 以 及 身份 验证 方式 。 这 是 本 书 唯一 没有 使 用 上 述 技术 构建 应 用 
的 一 章 。 








第 2 章 介 绍 Gist API、 几 个 命令 行 工具 ， 以 及 Ruby 语言 API 客户 端 Octokit。 然 后 ， 使 用 
Gist API 构建 一 个 简单 的 Ruby 服务 器 ， 存 储 并 显示 Gist。 








第 3 章 说 明 如 何 使 用 Gollum 命令 行 工 具 及 相关 的 Ruby 库 (gem)。Gollum 由 Grit 提供 支 
持 ，Grit 是 一 个 C 语言 绑 定 ， 用 于 访问 Git 仓库 。 我 们 还 会 说 明 Git 存储 格式 的 一 些 细节 ， 
在 Git 仓库 中 存储 大 文件 的 方式 ， 以 及 如 何 使 用 Git 命令 行 工具 访问 这 些 信 息 。 这 一 章 使 
用 Gollum 和 Grit 库 构 建 一 个 图 像 管理 工具 ， 不 过 它 仍 是 一 个 常规 的 Gollum 维基 ， 可 以 发 
布 到 GitHub 中 。 














第 4 章 探讨 Search API， 然 后 使 用 Python 构建 一 个 GUI 工具， 用 于 搜索 GitHub 中 的 
仓库 。 








第 5 章 介 绍 GitHub API 中 一 个 相对 新 的 部 分 ， 这 一 部 分 用 于 描述 第 三 方 工具 与 代码 之 间 的 
交互 。 这 一 章 使 用 C# 和 .NET GitHub API 库 Nancy 构建 一 个 应 用 。 














如 果 把 按 下 特定 方式 组 织 的 仓库 推送 到 GitHub 中 ，GitHub 会 将 其 转换 成 功能 完整 的 博客 ， 
基本 上 相当 于 WordPress 网 站 (当然 ， 没 那么 复杂 )。 第 6 章 说 明 仓 库 的 文件 结构 ， 如 何在 
Jekyll 网 站 中 使 用 Markdown， 如 何 使 用 Liquid 模板 引擎 提供 的 循环 结构 ， 以 及 如 何 使 用 
Ruby 语言 开发 一 个 工具 ， 从 Internet Archive 中 把 整个 网 站 导出 到 Jekyll 网 站 中 。 这 一 章 展 
示 如 何 使 用 缓存 朴 取 网 站 。 使 用 API 或 第 三 方 公开 信息 时 缓存 很 有 用 。 


第 7 章 为 Android 操作 系统 开发 一 个 移动 应 用 。 这 个 应 用 使 用 GitHub API 的 Git Data 部 分 
读 取信 息 ， 再 把 信息 写 入 一 个 Jekyll 网 站 仓库 。 这 一 章 展示 如 何 使 用 UI 测试 工具 Calabash 
为 Android 应 用 编写 用 户 界面 测试 ， 验 证 GitHub API 的 响应 。 




















Hubot 是 一 个 JavaScript (NodeJS) 聊天 机 器 人 ， 技术 人 员 使 用 它 可 以 更 进一步 ， 由 
“DevOps” (开发 运 维 ) 变 成 “ChatOps”( 聊 天 运 维 )。 第 8 章 说 明 如 何 使 用 GitHub API 的 
Activity 和 Pull Requests 部 分 。 此 外 ， 还 说 明 如 何 模拟 GitHub 的 通知 ， 以 及 如 何 编 写 可 测 
试 的 Hubot 扩展 (JavaScript 代码 通常 难以 测试 ) 。 我 们 将 把 这 些 串 在 一 起 ， 构 建 一 个 机 器 
人 ， 让 它 自 动 分 配 拉 取 请 求 审查 邀请 。 









































你 知道 可 以 把 整个 “ 单 页 应 用 ”托管 在 GitHub 中 吗 ? 第 9 章 说 明 如 何 使 用 JavaScript 语言 
构建 一 个 咖啡 店 信息 应 用 ， 这 个 应 用 的 数据 库 是 普通 的 文件 ， 托 管 在 GitHub 中 。 更 重要 
的 是 ， 我 们 将 展示 如 何 编写 可 测试 的 JavaScript 应 用 ， 说 明 如 何 模拟 所 需 的 GitHub API。 





本 书 不 会 介绍 Organizations APTI， 人 GitHub API 的 一 小 部 分 ， 作 用 简单 ， 只 能 列 出 
组 织 ， 以 及 修改 组 织 的 元 数据 。 学 会 GitHub API 的 其 他 部 分 后 ， 这 个 不 重要 的 部 分 自然 就 
会 用 了 。 

















Users API。 你 可 能 觉得 这 一 部 分 很 重要 ， 其 实 不 然 ，Users API 只 提供 
了 一 个 端点 ， 用 于 列 出 用 户 的 信息 、 添 加 或 删除 SSH 密 钥 、 修 改 电 子 邮 件 地 址 和 修改 关 
1 

本 书 没有 为 工 单 专 开 一 章 。 以 前 ，GitHub 把 工 单 和 拉 取 请 求 放 在 API 的 同一 部 分 中 ， 不 过 
拉 取 请 求 越 来 越 重 要 ， 所 以 GitHub API 文档 把 它 单独 列 为 一 部 分 。 其 实 ， 在 GitHub 内 部 ， 
二 者 仍然 存储 在 同一 个 数据 库 中 ， 而 且 拉 取 请 求 目 前 还 是 工 单 的 一 种 。 第 8 章 将 说 明 如 何 
使 用 拉 取 请 求 ， 工 单 可 以 比照 使 用 。 


























Enterprise API 几乎 与 GitHub.com 网 站 的 API 一 样 ， 本 书 没 有 单 写 一 章 介绍 企业 版 API 的 
用 法 ， 不 过 在 附录 B 中 举 了 几 个 示例 ， 说 明 如 何 使 用 企业 版 。 本 书 还 为 各 章 使 用 的 不 同 语 
言 提 供 了 企业 版 句法 ， 这 样 书 中 的 各 个 示例 就 能 在 企业 版 中 使 用 了 。 




















本 书 通过 这 些 故事 讲述 如 何 使 用 GitHub 背后 的 技术 ， 和 希望 借 此 让 你 一 宕 使 用 GitHub API 











构建 应 用 的 开发 者 是 如 何 思考 问题 的 。 


= 

本 书 的 目标 读者 

本 书 应 该 能 为 已 经 使 用 过 Git 或 GitHub 并 想 提升 技能 的 读者 提供 有 用 的 信息 。 没 有 用 过 
GitHub 或 Git 的 读者 应 该 先 读 一 本 入 门 书 。" 

你 应 该 至 少 熟悉 一 门 现代 的 命令 式 编程 语言 。 本 书 不 要 求 你 是 专家 级 程序 员 ， 但 是 要 有 一 
定 的 编程 经 验 ， 至 少 熟悉 一 门 编程 语言 。 





你 应 该 知道 HTTP 协议 的 基础 知识 。GitHub 团队 设计 API 时 采用 了 十 分 标准 的 REST 式 架 
构 。 你 应 该 知道 GET 请 求 和 POST 请 求 的 区 别 ， 至 少 要 知道 HTTP 状态 码 的 意思 。 

















如 果 熟 悉 其 他 Web API， 阅 读本 书 会 轻松 一 些 。 本 书 的 目标 是 告诉 你 如 何 使 用 架构 、 设 计 
和 测试 良好 的 API， 构 建 有 趣 且 强大 的 工具 。 如 果 你 没 怎么 用 过 Web API， 但 是 用 过 其 他 
类 型 的 API， 这 样 也 行 。 


你 将 学 到 什么 


本 书 主要 介绍 GitHub 和 强大 的 GitHub API 提供 的 功能 。 不 要 以 为 这 会 限制 你 对 Git 的 使 
用 。 假 如 你 是 Android 开发 者 ， 使 用 Git 管理 应 用 的 源码 ， 如 果 你 想 在 其 他 地 方 使 用 Git， 
没 问题 ， 本 书 能 打开 你 的 视野 ， 教 你 Git 和 GitHub 的 高 级 用 法 。 如 果 你 在 自己 的 项 目 中 
已 经 使 用 Git， 想 在 更 大 的 群体 中 推广 Git， 本 书 会 教 你 GitHub 引领 的 “社交 编程 ”风潮 。 
本 书 为 使 用 其 他 分 布 式 版 本 控制 系统 的 软件 开发 者 架 起 了 桥梁 ， 能 指引 他 们 转 用 Git 和 
GitHub 这 样 的 Web 服务 。 















































资深 开发 者 都 喜欢 自动 化 工具 。 本 书 提供 了 一 些 示例 ， 说 明 如 何 把 单调 的 任务 转换 成 可 
自动 和 重复 执行 的 过 程 。 这 些 示 例 使 用 多 门 编程 语言 编写 ， 让 你 了 解 如 何 与 GitHub API 
通信 。 








为 了 让 本 书 适 合 更 多 的 人 群 阅读 ， 我 们 没有 限定 必须 使 用 哪个 编辑 器 或 操作 系统 ， 很 多 示 
例 程 序 都 在 命令 行 中 执行 。 如 果 你 不 熟悉 命令 行 ， 本 书 能 让 你 深入 了 解 它 的 用 法 ， 相 信 你 
读 完 本 书 之 后 会 发 现 命令 行 的 强大 。 如 果 从 5 岁 起 你 的 爸爸 就 强迫 你 使 用 命令 行 ， 导致 你 
对 它 充满 恨 意 ， 那 么 通过 本 书 你 将 重新 爱 上 bash shell。 




















如 果 你 能 透 过 GitHub 提供 的 技术 看 到 其 背后 文化 和 思想 的 改变 ， 很 有 可 能 会 发 现 一 种 符 
合 现代 社会 的 工作 方式 。 本 书 集 中 精力 讨论 工具 本 身 ， 工 具 能 做 什么 则 由 你 自己 去 探索 。 


书 中 各 章 儿 乎 都 有 对 应 的 仓库 ， 这 些 仓库 托管 在 GitHub 中 ， 供 你 查看 书 中 讨论 的 代码 。 









































注 1: ”可 参考 《GitHub 入 门 与 实践 》 人 民 邮 电 出 版 社 出 版 。 一 一 编者 注 














并 
了 
x 
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你 可 以 随意 派生 这 些 示 例 ， 在 自己 的 项 目 和 工具 中 使 用 。 





最 后 ， 本 书 会 教 你 编写 可 测试 的 API 后 端 代码 。 即 便 是 最 有 经 验 的 开发 者 ， 往 往 也 觉得 为 
代码 编写 测试 是 件 有 挑战 的 事 ， 何 况 还 要 把 测试 代码 写 得 像 文 学 作品 那样 高 深 莫 测 。 测 试 
以 API 为 后 端的 程序 尤其 艰难 。 我 们 要 跳出 单元 测试 的 思维 ， 以 不 同 的 方式 思 芳 。 为 了 帮 
你 跨 过 这 道 障 得 ， 本 书 会 告诉 你 怎么 让 与 GitHub API 交互 的 代码 变 得 易于 测试 。 


GitHub 钟 爱 的 语言 


有 两 门 语言 与 GitHub 密 不 可 分 ， 你 要 安装 并 使 用 它们 才能 更 好 地 理解 本 书 的 内 容 。 




















。 Ruby 
这 是 一 门 简单 、 易 读 的 编程 语言 ，GitHub 公司 的 创始 人 在 公司 早期 广泛 使 用 。 








。 JavaScript 
这 是 唯一 普遍 使 用 的 浏览 器 端 编程 语言 ， 随 着 NodeJS 的 出 现 ， 甚 重要 性 迈 上 了 新 的 台 
阶 ， 其 至 与 开发 Web 应 用 的 服务 器 端 框架 Ruby on Rails 平起平坐 了 。 独 立 开发 者 尤其 


喜爱 该 语言 。 


























不 可 否认 ， 本 书 的 很 多 读者 都 已 经 熟悉 Ruby 或 JavaScript/NodeJS 了， 因此 正文 没有 说 明 
它们 的 基本 用 法 和 安装 方式 ， 而 是 放 到 了 附录 中 。 不 过 ， 附 录 也 没有 介绍 这 两 门 语言 的 句 
法 ， 我 们 希望 你 有 使 用 其 他 语言 的 经 验 ， 能 读 懂 任 何 命令 式 语言 编写 的 代码 。 书 中 各 章 讨 
论 GitHub API 的 方方面面 ， 偶 尔 会 讲解 语言 细节 ， 但 是 不 管 你 熟悉 哪 门 语言 ， 书 中 的 代码 
应 该 都 通俗 易 懂 。 附 录 讨 论 了 这 两 门 语言 在 GitHub 发 展 过 程 中 的 作用 ， 还 着 重 说 明了 一 
些 特殊 文件 的 作用 和 安装 方式 。 


安装 和 使 用 这 两 门 语言 不 会 浪费 你 的 时 间 ， 相 反 ， 能 为 你 建立 坚实 的 基础 ， 以 便 深 入 探索 
GitHub API。 书 中 有 儿童 使 用 Ruby 或 JavaScript， 所 以 花 点 时 间 学 习 基本 句法 有 助 于 更 好 
地 理解 书 中 的 内 容 。 


辣 
对 操作 系统 的 要 求 

本 书 是 两 位 作者 在 MacBook Pro 中 撰写 的 。MacBook 中 都 有 shell (“BASH”)， 与 任何 
Linux 设备 中 的 shell 几乎 一 样 。 如 果 你 使 用 这 两 个 操作 系统 ， 各 章 的 代码 都 能 顺利 运行 。 
















































































如 果 你 使 用 Windows 设备 (或 者 没有 BASH shell 的 操作 系统 ) ， 部 分 命令 和 代码 示例 可 能 
无 法 运行 ， 需 要 安装 额外 的 软件 才 行 。 




















简单 的 解决 方法 是 使 用 VirtualBox 和 Vagrant。VirtualBox 是 免费 的 虚拟 系统 ， 能 在 x86 
硬件 中 使 用 。Vagrant 是 开发 环境 管理 工具 。 使 用 VirtualBox 和 Vagrant 能 快速 安装 Linux 
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虚拟 机 。 如 果 想 安装 这 两 个 工具 ， 分 别 访问 VirtualBox (https:Wwww.virtualbox.org/wiki/ 
Downloads) 和 Vagrant (https:Wwww.vagrantup.com/downloads.html) 的 下 载 页 面 。 安 装 好 
之 后 ， 可 以 使 用 下 述 两 个 命令 安装 Ubuntu 虚拟 机 : 














$ vagrant init hashicorp/precise32 
$ vagrant up 


壬 全 襄 ] -二 1 去 

不 适合 阅读 本 书 的 读者 

本 书 探讨 GitHub API 的 用 法 ， 没 有 限定 于 单一 的 语言 ， 而 是 使 用 多 门 不 同 的 语言 。 本 书 不 
仅 说 明了 GitHub 团队 设计 API 的 方式 ， 还 分 析 了 不 同 编程 语言 和 社区 对 客户 端 库 的 实现 
方式 。 我 们 相信 这 样 能 教 你 更 多 知识 ， 因 此 ， 如 果 你 只 对 某 一 门 语 言 感 兴趣 ， 想 知道 如 何 
使 用 那 门 语言 与 GitHub API 交互 ， 那 么 这 本 书 就 不 适合 你 。 





























本 书 努 力 证 明 API 驱动 的 代码 可 以 测试 ， 而 且 这 么 做 是 有 好 处 的 。 但 是 本 书 不 是 测试 编写 
手册 ， 不 会 教 你 怎么 写 出 最 好 的 测试 代码 。 我 们 使 用 多 门 语 言 ， 为 的 是 不 加 入 各 个 社区 对 
测试 框架 的 争论 。 我 们 认识 到 多 数 软件 项 目 完全 没有 测试 ， 因 此 本 书 的 重点 是 帮 你 跨 过 这 
只 大 拦路 虎 。 如 果 你 从 未 写 过 测试 ， 那 么 要 转换 一 下 思维 方式 。 我 们 希望 通过 具体 的 示例 
让 你 (尤其 是 没有 写 过 测试 的 读者 ) 知道 如 何 为 使 用 API 的 代码 编写 测试 。 有 些 章节 对 应 
的 仓库 中 有 更 详细 的 测试 组 件 ， 书 中 的 测试 大 都 简略 ， 没 有 涵盖 全 部 边缘 情况 。 


排版 约定 


本 书 使 用 了 下 述 排版 约定 。 














。 楷体 
表示 新 术语 。 

。 等 宽 字 体 (constant width) 
表示 程序 片段 ， 以 及 正文 中 出 现 的 变量 、 函 数 名 、 数 据 库 、 数 据 类 型 、 环 境 变 量 、 语 
句 和 关键 字 等 。 








。 加 粗 等 宽 字体 (constant width bold) 
表示 应 该 由 用 户 输入 的 命令 或 其 他 文本 。 











。 和 斜体 等 宽 字 体 (Constant width italic) 
表示 应 该 志 换 成 用 户 提供 的 值 ， 或 者 由 上 下 文 决 定 的 值 。 





这 个 图 标 表 示 一 般 性 说 明 。 


这 个 图 标 表 示警 告 或 提醒 。 





使 用 代码 示例 


补充 材料 (代码 示例 、 练 习 等 ) 可 以 从 https://github.com/xrd/building-tools-with-github 
下 载 。 


本 书 是 要 帮 你 完成 工作 的 。 一 般 来 说 ， 如 果 本 书 提供 了 示例 代码 ， 你 可 以 把 它 用 在 你 的 程 
序 或 文档 中 。 除 非 你 使 用 了 很 大 一 部 分 代码 ， 否 则 无 需 联系 我 们 获得 许可 。 比 如 ， 用 本 书 
的 几 个 代码 片段 写 一 个 程序 就 无 需 获 得 许可 ， 销 售 或 分 发 O"Reilly 图 书 的 示例 光盘 则 需要 
获得 许可 ， 引 用 本 书 中 的 示例 代码 回答 问题 无 需 获得 许可 ， 将 书 中 大 量 的 代码 放 到 你 的 产 
品 文档 中 则 需要 获得 许可 。 









































我 们 很 希望 但 并 不 强制 要 求 你 在 引用 本 书 内 容 时 加 上 引用 说 明 。 引 用 说 明 -一般 包括 书 名 、 
作者 、 出 版 社 和 ISBN。 比 如 :“Brilding Tools with GitHub by Chris Dawson and Ben Straub 
(O’Reilly). Copyright 2016 Chris Dawson and Ben Straub, 978-1-491-93350-3.” 











如 果 你 觉得 自己 对 示例 代码 的 用 法 超出 了 上 述 许可 的 范围 ， 欢 迎 你 通过 permissions@ 
oreilly.com 与 我 们 联系 。 





Safari2 Books Online 


Safari Books Online (http:/www.safaribooksonline.com) 是 应 运 

Sa fa 及 和 而 和 的 数字 图 书馆 。 它 同时 以 图 书 和 视频 的 形式 出 版 世界 顶级 

Books Online 技术 和 商务 作家 的 专业 作品 。 技 术 专 家 、 软 件 开发 人 员 、Web 

设计 师 、 商 务 人 士 和 创意 专家 等 ， 在 开展 调研 、 解 决 问 题 、 学 习 和 认证 培训 时 ， 都 将 
Safari Books Online 视 作 获取 资料 的 首选 渠道 。 














对 于 组 织 团体 、 政 府 机 构 和 个 人 ，Safari Books Online 提供 各 种 产品 组 合 和 灵活 的 定 
价 策略 。 用 户 可 通过 一 个 功能 完备 的 数据 库 检 索 系 统 访问 O'Reilly Media、Prentice 
Hall Professional、Addison-Wesley Professional、 Microsoft Press、Sams、Que、Peachpit 











Press、 Focal Press、 Cisco Press、John Wiley & Sons、 Syngress、 Morgan Kaufmann、IBM 
Redbooks、 Packt、Adobe Press、 FT Press、Apress、Manning、New Riders、McGraw-Hill、 
Jones 多 Bartlett、Course Technology 以 及 其 他 儿 十 家 出 版 社 的 上 千 种 图 书 、 培 训 视 频 和 正 








式 出 版 之 前 的 书稿 。 要 了 解 Safari Books Online 的 更 多 信息 ， 我 们 网 上 见 。 


联系 我 们 
请 把 对 本 书 的 评价 和 问题 发 给 出 版 社 。 
美国 : 














O’Reilly Media, Inc. 
1005 Gravenstein Highway North 
Sebastopol, CA 95472 


中 国 : 


北京 市 西城 区 西直门 南大 街 2 号 成 馈 大 厦 C 座 807 室 (100035) 
奥 莱 利 技术 咨询 (北京) 有 限 公 司 


O’Reilly 的 每 一 本 书 都 有 专属 网 页 ， 你 可 以 在 那儿 找到 本 书 的 相关 信息 ， 包 括 勘 误 表 、 





例 代码 以 及 其 他 信息 。 本 书 的 网 站 地 址 是 : 
http://shop.oreilly.com/product/0636920043027.do 





对 于 本 书 的 评论 和 技术 性 问题 ， 请 发 送 电 子 邮件 到 : bookquestions@oreilly.com 





要 了 解 更 多 O’Reilly 图 书 、 培 训 课 程 、 会 议和 新 闻 的 信息 ， 请 访问 以 下 网 站 : 


http://www.oreilly.com 











我 们 在 Facebook 的 地 址 如 下 : http://facebook.com/oreilly 
请 关注 我 们 的 Twitter 动态 : http://twitter.com/oreillymedia 


我 们 的 YouTube 视频 地 址 如 下 : http:/www.youtube.com/oreillymedia 
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第 1 章 


开放 的 GitHub AP1 





本 章 开 始 介绍 如 何 使 用 GitHub API 读 写 数据 。 后 续 的 章节 说 明 如 何 使 用 不 同 的 客户 端 库 通 
过 GitHub API 访问 信息 。 这 些 客 户 端 库 故意 隐藏 API 的 具体 细节 ， 为 你 提供 简洁 且 符 合 
习惯 的 方法 ， 用 于 访问 托管 在 GitHub 中 的 Git 仓库 ， 查 看 和 修改 里 面 的 数据 。 不 过 ， 本 章 
直接 分 析 GitHub API， 详 细 说 明 原始 HTTP 请 求 和 响应 。 本 章 还 会 讨论 访问 GitHub 中 公 
开 和 隐私 数据 的 不 同方 式 ， 并 指出 各 自 的 不 足 之 处 。 此 外 ， 本 章 会 概述 网 络 受 限时 如 何在 
Web 训 览 器 中 访问 GitHub 的 数据 。 





1.1 cURL 


有 时， 你 可 能 想 立 即 通 过 GitHub API 访问 信息 ， 而 不 想 编写 正式 的 程序 ， 有 时 ， 你 可 能 想 
立即 获取 HTTP 原始 请 求 的 首部 和 内 容 ， 有 时 ， 你 甚至 可 能 会 对 客户 端 库 的 实现 有 疑惑 ， 
需要 换个 角度 确认 客户 端 库 的 行为 是 否 正确 。 遇 到 这 些 情况 时 ， 最 适合 使 用 cURL 这 个 简 
单 的 命令 行 HTTP 工具 。 与 最 优秀 的 Unix 工具 一 样 ，cURL 是 个 小 型 程序 ， 功 能 十 分 专 
一 ， 而 且 故 意 做 了 限制 ， 只 用 于 访问 HTTP 服务 器 。 





cURL 与 它 熟 说 的 HTTP 协议 一 样 是 无 状态 的 。 后 面 有 一 章 会 探讨 这 一 局 限 性 的 解决 方法 ， 
不 过 要 注意 ，cURL 最 适合 用 于 发 起 一 次 性 请 求 。 


安装 cURL 


大 多 数 OS X 设备 中 通常 都 安装 了 cURL， 在 Linux 中 可 以 使 用 包 管理 器 轻易 
安装 (执行 apt-get instaLL curtL 或 yum install curl 命令 )。 如 果 使 用 的 
是 Windows， 或 者 想 自己 动手 安装 ,请 访问 http://curl.haxx.se/download.html。 








下 面 来 发 起 一 个 请 求 。 我 们 从 GitHub API 最 基本 的 端点 入手， 地 址 是 https://api.github. 


com。 
$ curl https://api.github.com 


"current_user_url": "https://api.github.com/user", 
"current_user_authorizations_html_url": 
"https://github.com/settings/connections/applications{/client_id}", 
"authorizations_url": "https://api.github.com/authorizations", 
"code_search_url": 
"https://api.github.com/search/code?q={query}{&page,per_page,sort,order}", 
"emails_url": "https://api.github.com/user/emails", 

"emojis_url": "https://api.github.com/emojis", 


和 





为 了 便于 了 阅读， 此 处 省 略 了 部 分 响应 。 有 几 点 需要 特别 注意 : 响应 中 有 大 量 指向 附属 信息 
的 URL，URL 中 包含 参数 ， 此 外 响应 的 格式 是 JSON。 


我 们 从 这 个 API 的 响应 中 能 得 知 什么 呢 ? 


1.2 ”列举 API 路 径 


GitHub API 是 超 媒体 API。 超 媒体 的 构成 需要 用 一 整 本 书 才 能 说 清楚 (推荐 阅读 《使 用 
HTML5 和 Node 构建 超 媒 体 API》) ， 不 过 通过 分 析 响 应 ， 我 们 能 掌握 超 媒体 的 多 数 核心 
概念 。 首 先 ， 从 前 面 那个 API 的 响应 可 以 看 出 ， 响 应 中 包含 一 个 映射 ， 列 出 了 接 下 来 可 
能 会 发 起 请 求 的 地 址 。 当 然 ， 不 是 所 有 客户 端 都 会 使 用 这 个 信息 ， 但 是 超 媒体 API 的 目 
标 之 一 ， 是 让 客户 端 在 不 重新 编写 代码 的 前 提 下 动态 调整 所 用 的 端点 。 如 果 你 觉得 编写 客 
户 端 时 要 考虑 自动 处 理 新 端点 ， 以 防 GitHub 更 改 API 这 一 点 难以 理解 ， 不 用 太 过 担心 ， 
GitHub 非常 负责 ， 它 像 大 多 数 公司 那样 ， 积 极 维护 API 并 为 其 提供 支持 。 不 过 要 知道 ， 
API 中 的 API 参考 是 值得 信赖 的 ， 比 外 部 文档 可 信 ， 因 为 文档 可 能 与 API 本 身 脱 节 。 





















































API 中 的 映射 富 含 数据 。 例 如 ， 映 射 不 仅 包含 URL， 还 有 为 URL 提供 参数 的 方式 。 在 前 
而 那个 示例 中 ，code_search_url 键 对 应 的 URL 明显 用 于 在 GitHub 中 搜索 代码 ， 此 外 还 指 
明了 如 何 构 建 传 给 URL 的 参数 。 如 果 客 户 端 够 智能 ， 能 读 懂 这 种 纲领 性 的 格式 ， 就 能 万 
态 生 成 查询 ， 无 需 开 发 者 去 阅读 API 文档 。 至 少 ， 这 是 超 媒体 为 我 们 指明 的 美好 未 来 。 如 
果 你 是 怀疑 论 者 ， 至 少 要 知道 API (比如 GitHub) 把 文档 嵌入 自身 当中 ， 并 且 GitHub 做 
了 足够 的 测试 ， 能 够 证 明 内 寿 的 文档 与 API 端点 传递 的 信息 匹配 。 甚 他 类 型 的 API 则 没有 
这 么 强 的 保障 。 















































下 面 ， 我 们 来 简单 讨论 所 有 GitHub API 的 响应 格式 一 一 JSON。 





1.3 JSON 格 式 


GitHub API 返 回 的 所 有 响应 都 是 JSON (JavaScript Object Notation，JavaScript 对 象 表 
示 法 ) 格式 。JSON 是 一 种 “ 轻 量 级 数据 交换 格式 ”( 详 情 参见 JSON.org 网 站 : http:/ 
www.json.org/)。 此 外 ， 还 有 其 他 与 之 相 争 且 有 效 的 格式 ， 例 如 XML (Extensible Markup 
Language， 可 扩展 标记 语言 ) 和 YAML (YAML Ain’*t Markup Language)， 不 过 JSON 正 
在 快速 成 为 Web 服务 的 事实 标准 。 








JSON 之 所 以 如 此 流行 ， 有 以 下 两 个 原因 。 


。 JSON 易于 阅读 。 与 XML 等 序列 化 格式 相 比 ，JSON 很 好 地 平衡 了 人 类 可 读 性 。 
。 只 需 小 幅 修改 (和 程序 员 的 认 知 处 理 )，JSON 就 能 在 JavaScript 中 使 用 。 在 客户 端 和 服 
务 器 端 都 能 同样 良好 使 用 的 数据 格式 一 定 会 胜出 ，JSON 就 是 如 此 。 








GitHub 最 初 使 用 Ruby on Rails 工具 栈 开发 (部 分 代码 现在 仍 在 运行 )， 你 可 能 觉得 这 样 的 
网 站 应 该 支持 指定 替代 格式 (如 XML)， 但 是 GitHub 不 再 支持 XML 了 。JSON 万 岁 | 





如 果 你 用 过 其 他 基于 文本 的 交换 格式 ， 会 发 现 JSON 特别 简单 。 注 意 ，JSON 只 支持 使 用 
双 引 号 ， 不 支持 单 引 号 ， 这 一 点 对 于 刚 接触 JSON 的 人 来 说 可 能 有 点 难以 理解 ， 出 乎 意料 。 

















我 们 使 用 cURL 这 个 命令 行 工具 从 GitHub API 中 获取 数据 。 如 果 再 有 一 个 简单 的 命令 行 工 
具 能 处 理 JSON 就 好 了 。 下 面 介 绍 一 个 这 样 的 工具 。 



































1.3.1 在 命令 行 中 解析 JSON 

JSON 是 一 种 文本 格式 ， 因 此 可 以 使 用 任何 命令 行文 本 处 理工 具 处 理 JSON 响应 ， 例 如 令 
人 敬仰 的 AWK。 有 一 个 专门 解析 JSON 的 优秀 工具 能 补足 cURL， 值 得 一 用 ， 这 便 是 jq。 
通过 管道 (大 多 数 shell 使 用 “|” 字 符 ) 把 JSON 内 容 传 给 jq 后 ， 可 以 使 用 过 滤器 轻易 提 
取 JSON 片段 。 



































安装 jq 

jq 可 以 从 源码 安装 ， 使 用 包 管 理 器 安装 (例如 brew 或 apt-get)， 下 载 页 面 
(http://stedolan.github.io/jq/download/) 还 有 适用 于 OS X、Linux、Windows 
和 Solaris 的 二 进 制 文件 。 











才 











而 深入 前 面 的 示例 ， 从 访问 api.github.com 后 收 到 的 API 映射 中 提取 感 兴 趣 的 信息 : 


$ curl https://api.github.com | jq '.current user_url' 


% Total % Received % Xferd Average Speed ”Time Time Time Current 
Dload Upload Total Spent Left Speed 
100 2004 100 2004 0 0 4496 0 --:--:-- -1 - 4493 


"https://api.github.com/user" 
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发 生 了 什么 ? jq 工具 解析 JSON， 然 后 使 用 .current_user_url 过 滤器 从 JSON 响应 中 获取 
内 容 。 再 次 查看 响应 ， 你 会 发 现 响 应 是 个 关联 数组 ， 里 面 有 多 个 键 值 对 。jdq 使 用 那个 关联 
数组 中 的 current_user_url 作为 键 获 取 对 应 的 值 。 





你 还 会 发 现 cURL 把 传输 时 间 信 息 打印 出 来 了 。cURL 把 这 些 信息 打印 到 标准 错误 。 这 是 
shell 的 一 种 约定 ， 用 于 输出 错误 。jq 会 正确 忽略 这 个 输出 流 (也 就 是 说 ，JSON 格式 的 数 
据 流 不 会 被 错误 消息 搅乱 )。 如 果 想 禁止 那些 信息 ， 让 请 求 清晰 明了 ， 可 以 使 用 -s 开关 ， 
在 “静默 ”模式 中 运行 cURL。 

jq 在 JSON 响应 上 应 用 过 滤器 的 方式 易于 理解 。 下 面 通过 一 个 复杂 的 请 求 ( 例 如， 获取 某 
个 用 户 的 所 有 公开 仓库 ) 说 明 如 何 使 用 jq 的 模式 参数 。 我 们 要 获取 一 组 更 为 复杂 的 信息 ， 
即 用 户 的 仓库 列表 ， 以 此 说 明 如 何 使 用 jq 从 响应 中 提取 信息 : 
































$ curl -s https://api.github.com/users/xrd/repos 
[ 
{ 
"id": 19551182, 
"Name": "a-gollum-test", 
"full_name": "xrd/a-gollum-test", 
"owner": { 
"login": "xrd", 
"id": 17064， 
"avatar_url": 
"https://avatars.githubusercontent.com/y/17064?v=3", 


} 
] 
$ curl -s https://api.github.com/users/xrd/repos | jq '.[0].owner.id' 
17064 
这 个 响应 的 结构 与 之 前 不 同 ， 它 不 是 一 个 关联 数组 ， 而 是 一 个 普通 数组 (有 多 个 元 素 )。 
为 了 获取 第 一 个 元 素 ， 我 们 要 指定 数字 索引 ， 然 后 再 通过 键 进入 元 素 里 的 关联 数组 ， 从 而 
获取 所 需 的 内 容 一 一 属 主 的 ID。 


jq 工具 能 很 好 地 检查 JSON 的 有 效 性 。 前 面 说 过 ，JSON 的 键 值 对 只 能 使 用 双 引 号 ， 不 能 
使 用 单 引 号 。 可 以 使 用 jq 验证 JSON 是 否 有 效 ， 以 及 是 否 满足 这 个 要 求 : 


























$ echo '{ "aa" : "bb" }' | jq 和 


{ 
"ar nb" 
} 
$ echo "{ 'no' : 'bueno' }" | jq "." 


parse error: Invalid numeric literal at line 1, column 7 
传 给 jq 的 第 一 个 JSON 是 有 效 的 ， 而 第 二 个 JSON 使 用 了 无 效 的 单 引 号 字符 ， 因 此 报错 


了 。jq 过 滤器 是 以 字符 串 形 式 传递 的 参数 ， 而 把 字符 串 提 供给 jq 的 shell 不 管 你 使 用 的 是 
单 引 号 还 是 双 引 号 ， 从 上 述 代码 可 以 看 出 这 一 点 。 如 果 你 不 知道 echo 命令 的 作用 ， 我 告诉 
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你 ， 它 会 把 传 给 它 的 任何 字符 串 打印 出 来 。 把 这 个 命令 和 管道 符号 结合 起 来 ， 可 以 通过 标 
pe 供给 jq。 





jq 是 个 强大 的 工具 ， 能 从 任何 JSON 响应 中 迅速 获取 内 容 。 此 外 ,jdq 还 有 很 多 强大 的 功 
能 ， 详 情 参见 文档 (https:/stedolan.github.io/jq/) 。 


至 此 ， 我 们 知道 如 何 仅 使 用 一 行 命令 完成 从 GitHub API 中 获取 所 需 的 信息 ， 并 从 响应 中 解 
析出 信息 片段 。 可 是 ， 有 时 为 cURL 或 API 指定 的 参数 可 能 是 错误 的 ， 获 得 的 数据 不 是 我 
们 想 要 的 。 接 下 来 ， 我 们 学 习 如 何 调试 cURL 工具 和 API 服务 本 身 ， 从 而 在 出 错时 获取 更 
多 的 信息 。 








1.3.2 ”cURL 的 调试 开关 

前 面 说 过 ，cURL 是 验证 响应 是 否 与 预期 相符 的 绝 佳 工具 。 响 应 主体 很 重要 ,但 是 通常 还 
要 获取 首部 。 为 cURL 指定 -i 和 -v 开关 能 轻易 获取 这 些 信 息 。-i 开关 打印 请 求 首部 ，- 
开关 则 打印 请 求 和 响应 首部 (> 符号 表示 请 求 数据 ，< 符号 表示 响应 数据 )。 





























$ curl -i https://api.github.com 

HTTP/1.1 200 OK 

Server: GitHuyub.com 

Date: Wed, 03 Jun 2015 19:39:03 GMT 
Content-Type: application/json; charset=utf-8 
Content-Length: 2004 

Status: 200 OK 

X-RateLimit-Limit: 60 


"current_user_url": "https://api.github.com/user", 


curl -v https://api.github.com 
Rebuilt URL to: https://api.github.com/ 
Hostname was NOT found in DNS cache 
Trying 192.30.252.137... 
Connected to api.github.com (192.30.252.137) port 443 (#0) 
successfully set certificate verify locations: 
CAfile: none 
CApath: /etc/ssL/certs 
SSLv3, TLS handshake, Client hello (1): 
* SSLv3, TLS handshake, Server hello (2): 


光 A Ve 


光 


CN=DigiCert SHA2 High Assurance Server CA 
SSL certificate verify ok. 

GET / HTTP/1.1 

User-Agent: curl/7.35.0 

Host: api.github.com 

Accept: */* 


光 光 。 


AV Vv VVvV 


HTTP/1.1 200 OK 
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* Server GitHub.com is not blacklisted 





指定 -v 开关 能 获取 所 有 信息 : DNS 查询 、SSL 证 书 链 中 的 信息 ， 以 及 完整 的 请 求 和 响应 
自 


注意 ， 如 果 打印 首部 ，jq 这 样 的 工具 会 迷惑 不 解 ， 因 为 提供 的 不 是 纯粹 的 
JSON。 








本 节 旨 在 说 明 不 仅 主体 (JSON 数据 ) 中 有 值得 关注 的 信息 ， 首 部 中 也 有 。 我 们 要 知道 有 
哪些 首部 ， 还 要 知道 哪些 是 重要 的 。 根 据 HTTP 规范 ， 需 要 的 首部 有 很 多 ， 这 些 首部 通常 
可 以 忽略 ， 不 过 如 果 请 求 不 是 相互 独立 的 ， 有 些 首部 则 是 必 不 可 少 的 。 


1.4 重要 的 首部 


GitHub API 的 每 个 响应 中 都 有 三 个 用 于 指明 API 频率 限制 的 首部 ， 分 别 是 X-RateLimit- 
Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。 这 些 限 制 在 1.7.6 节 详 述 。 








从 GitHub API 中 获取 文本 或 blob 内 容 时 ， 要 用 到 X-GitHub-Media-Type 首部 中 包含 的 信 
息 。 向 GitHub API 发 起 请 求 时 ， 可 以 在 请 求 中 发 送 Accept 首部 ， 指 明 想 使 用 的 格式 。 

















下 面 ， 我 们 使 用 一 个 响应 构建 另 一 个 响应 。 


1.5 跟随 超 媒 体 API 


我 们 要 使 用 API 基 端点 返回 的 “映射 ”， 手 动 生成 另 一 个 请 求 : 





$ curl -i https://api.github.com/ 
HTTP/1.1 200 OK 

Server: GitHuyub.com 

Date: Sat, 25 Apr 2015 05:36:16 GMT 


"current user_url": "https://api.github.com/user", 
"Organtzatton vel "https://api.github.com/orgs/{org}", 
和 
我 们 可 以 使 用 组 织 的 URL， 把 占 位 符 替 换 成 "github": 





curl https://api.github.com/orgs/github 


ke 


"login": "github", 
"id": 9919, 
"url": "https://api.github.com/orgs/github", 


"description": "GitHub, the company.", 
"name": "GitHub", 

"company": null, 

"blog": "https://github.com/about", 
"location": "San Francisco, CA", 
"email": "support@github.com", 


"created_at": "2008-05-11T04:37:312Z"， 
"updated_at": "2015-04-25T05:17:012Z"， 
"type": "Organization" 


} 
通过 上 述 信 息 可 以 得 知 GitHub 的 一 些 信息 。 我 们 得 知 GitHub 的 博客 地 址 是 https://github. 
com/about， 公 司 位 于 旧金山 ， 组 织 的 创建 日 期 是 2008 年 5 月 11 日 。 从 博客 中 一 篇 发 布 于 
4 月 份 的 文章 (https://github.com/blog/40-we-launched) 中 得 知 ，GitHub 公司 在 这 一 个 月 之 
前 就 成 立 了 。 或 许 公 司 成 立 一 个 月 之 后 才 在 GitHub 网 站 中 添加 组 织 功 能 吧 。 























目前 ， 我 们 发 起 的 请 求 都 用 于 获取 公开 信息 。GitHub API 提供 的 信息 十 分 丰富 ， 但 是 验证 
身份 之 后 才能 访问 隐私 信息 和 不 可 公开 使 用 的 服务 。 例 如 ， 想 使 用 API 向 GitHub 中 写 入 
数据 的 话 ， 需 要 知道 如 何 验证 身份 。 


1.6 身份 验证 


向 GitHub API 发 起 请 求 时 ， 有 两 种 身份 验证 方式 ， 用户 名 和 密码 (HTTP 基本 验证 ) 以 及 
OAuth 令 牌 。 


1.6.1 用 户 名 和 密码 验证 


提供 用 户 名 和 密码 后 可 以 访问 GitHub 中 受 保护 的 内 容 。 用 户 名 验证 使 用 HTTP 基本 验证 
实现 ， 在 cURL 中 使 用 -u 标 志 指 定 。HTTP 基本 验证 就 是 用 户 名 和 密码 验证 ; 








$ curl -uyu xrd https://api.github.com/rate_limit 
Enter host password for user 'xrd': Xxxxxxxx 


{ 
"rate": { 
"limit": 5000, 
"remaining": 4995， 
"reset": 1376251941 
} 
} 
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上 述 cURL 命令 先 通过 GitHub API 的 身份 验证 ， 然 后 获取 该 用 户 账号 具体 的 频率 限制 信 
息 。 这 些 是 受 保护 的 信息 ， 只 有 登录 的 用 户 才能 查看 。 


1. 用 户 名 验证 的 优点 

几乎 所 有 客户 端 库 都 支持 HITP 基本 验证 。 我 们 即将 介绍 的 GitHub API 客户 端 都 支持 用 
户 名 和 密码 验证 。 而 且 ， 自 己 实 现 客户 端 也 很 容易 ， 因 为 这 是 HITP 标准 的 核心 功能 。 所 
以 ， 开 发 客户 端 时 只 要 使 用 了 符合 标准 的 HTTP 库 ， 就 能 访问 GitHub API 中 的 内 容 。 


2. 用 户 名 验证 的 缺点 
使 用 用 户 名 和 密码 验证 管理 GitHub API 的 访问 权限 不 合适 ， 原 因 有 如 下 几 个 。 









































。 HTTP 基本 验证 是 旧 协 议 ， 没 有 预料 到 Web 服务 的 粒度 如 此 细 化 。 如 果 通 过 用 户 名 和 
密码 验证 用 户 的 身份 ， 那 么 无 法 指定 让 Web 服务 开放 哪些 特定 的 功能 。 

。 如 果 使 用 用 户 名 和 密码 在 手机 端 访问 GitHub API 的 内 容 ， 又 在 笔记 本 电脑 中 访问 API 
的 内 容 ， 那 就 无 法 禁止 某 一 台 设 备 访问 ， 只 能 都 禁止 。 

。 HTTP 基本 验证 无 法 扩展 验证 流程 。 现 今 ， 很 多 现代 服务 都 支持 双重 身份 验证 ， 为 了 把 
这 种 验证 方式 插入 现 有 的 验证 过 程 ， 需 要 修改 HTTP 客户 端 (例如 Web 浏览 器 )， 至 少 
也 要 修改 客户 端 预 期 的 流程 (让 浏览 器 重复 请 求 )。 

















这 些 问 题 在 OAuth 流程 中 都 能 得 到 解决 (或 者 至 少 得 到 支持 )。 
性 至 上 时 才 应 当 使 用 用 户 名 和 密码 验证 身份 。 


鉴于 这 些 缺 点 ， 仅 当 便 利 





1.6.2 OAuth 
OAuth 是 一 种 身份 验证 机 制 ， 把 令 牌 与 功能 或 客户 端 绑 定 起 来 。 也 就 是 说 ， 可 以 指定 让 服 
务 为 OAuth 令 牌 开 放 哪些 功能 ， 还 可 以 颁发 多 个 令 牌 ， 与 不 同 的 客户 端 绑 定 ， 例 如 手机 应 
用 、 笔 记 本 电脑 、 智 能 手表 ， 甚 至 是 接 入 物 联 网 的 烤箱 。 更 重要 的 是 ， 可 以 吊销 令 牌 而 不 
对 其 他 令 牌 产生 影响 。 











OAuth 令 牌 主要 的 缺点 是 增加 了 一 层 复杂 度 ， 如 果 你 只 用 过 HTTP 基本 验证 ， 对 此 可 能 不 
熟悉 。HTTP 基本 验证 通常 只 需 在 HTTP 请 求 中 添加 一 个 额外 的 首部 ， 或 者 在 客户 端 工具 
(如 cURL) 中 添加 一 个 额外 的 标志 。 





OAuth 能 解决 上 述 问题 ， 方 法 是 把 令 牌 限定 在 作用 域 (指定 Web 服务 的 功能 子 集 ) 中 ， 以 
及 按 需 为 不 同 的 客户 端 生成 不 同 的 令 牌 。 


1. 作用 域 : 指定 验证 令 牌 可 执行 的 操作 

生成 OAuth 令 牌 时 ， 要 指定 所 需 的 访问 权限 。 下 述 示例 虽然 使 用 HITP 基本 验证 创建 令 
牌 ， 但 是 一 旦 得 到 令 牌 ， 后 续 请 求 就 不 再 需要 使 用 HITP 基本 验证 。 获 颂 OAuth 令 牌 之 
后 ， 便 有 权限 读 写 相 应 用 户 的 公开 仓库 。 
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下 述 cURL 命令 使 用 HTTP 基本 验证 请 求 令 牌 ， 


$ curl -U Username -d '{"scopes":["public repo"]}' \ 
https://api.github.com/authorizations 


"id": 1234567， 
"url": "https://api.github.com/authorizations/1234567", 
"app": { 
"name": "My app", 
"url": "https://developer.github.com/v3/o0auth_authorizations/", 
"client_id": "00000000000000000000" 
}， 
"token": "abcdef87654321 





请 求 成 功 后 获得 的 JSON 啊 应 中 有 个 令 牌 ， 把 它 提取 出 来 之 后 可 以 提供 给 应 用 ， 用 于 访问 
GitHub API。 


如 果 使 用 双重 身份 验证 ， 这 个 过 程 需要 额外 的 步骤 ， 详 情 参 阅 第 8 章 。 
令 牌 的 使 用 方法 是 ， 在 Authorization 首部 中 指定 令 牌 : 
$ curl -H "Authorization: token abcdef87654321" . . . 


作用 域 明 确 了 服务 或 应 用 能 如 何 使 用 GitHub API 中 的 数据 。 对 于 供用 户 自己 使 用 的 令 牌 来 
说 ， 作 用 域 便 于 稽查 用 户 如 何 使 用 API 提供 的 信息 。 不 过 ， 当 第 三 方 应 用 想 访问 你 的 信息 
时 ， 最 能 体现 作用 域 明确 访问 权限 的 重要 价值 和 防护 作用 ， 因 为 你 能 确保 应 用 只 能 访问 允 
许 它 访问 的 数据 ， 而 且 便 于 取消 访问 权限 。 


2. 作用 域 的 不 足 
要 知道 ， 作 用 域 有 个 极 大 的 不 足 之 处 : 无 法 精细 调整 特定 仓库 的 访问 权限 。 如 果 允 许 访问 
任何 一 个 私有 仓库 ， 那 么 所 有 仓库 就 都 能 访问 。 





未 来 ，GitHub 可 能 会 修改 作用 域 的 工作 方式 ， 解 决 其 中 一 些 问题 。OAuth 机 制 的 好 处 是 ， 
发 生变 化 后 ， 只 需 请 求 重新 设 定 作 用 域 的 令 牌 应 用 的 身份 验证 流程 则 无 需 修改 。 








构建 服务 或 应 用 时 ， 要 特别 谨慎 地 对 待 请 求 的 作用 域 。 用 户 会 担忧 交 给 你 
的 数据 是 否 安全 (这 是 正常 的 )， 他 们 会 根据 请 求 的 作用 域 评 估 能 否 信任 
应 用 。 如 果 用 户 觉得 不 需要 那么 广 的 作用 域 ， 请 求 授 权时 一 定 要 从 提供 给 
GitHub 的 权限 列表 中 删除 ， 与 用 户 建立 一 定 的 信任 之 后 再 考虑 升级 为 更 广 
的 作用 域 。 

















3. 逐步 升级 作用 域 
你 可 以 先 请 求 严格 受 限 的 作用 域 ， 以 后 再 请 求 更 广 的 作用 域 。 例 如 ， 用 户 首次 访问 你 的 应 
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用 时 ， 你 可 以 只 获取 user 作用 域 ， 在 你 的 服务 中 创建 用 户 对 象 ， 仅 当 应 用 需要 获取 用 户 
的 仓库 信息 时 再 请 求 升级 权限 。 此 时 ， 用 户 需要 接受 或 拒绝 升级 请 求 。 但 是 ， 事 无 巨细 ， 
(在 与 用 户 建立 关系 之 前 ) 什么 都 询问 ， 往 往 会 导致 用 户 放弃 登录 。 


下 面 详 述 使 用 OAuth 验证 身份 的 细节 。 











4. 简化 的 OAuth 流 程 
OAuth 有 很 多 版 本 ，GitHub 使 用 的 是 OAuth2。OAuth2 验证 身份 的 流程 如 下 : 


(1) 应 用 请 求 访问 ， 

(2) 服务 提供 方 (GitHub) 请 求 验证 身份 ， 通 常 使 用 用 户 名 和 密码 ; 

(3) 如 果 启 用 了 双重 身份 验证 ， 询 问 OTP (one-time password， 一 次 性 密码 ) ; 
(4) GitHub 返回 包含 令 牌 的 JSON 响应 ; 

(5) 应 用 使 用 OAuth 令 牌 请 求 API。 























接 下 来 说 明 GitHub API 在 通信 过 程 中 用 于 提供 反馈 的 各 个 HTTP 状态 码 。 


1.7 ”状态 人 码 


GitHub API 使 用 HTTP 状态 码 明确 表明 请 求 的 处 理 结果 。 如 果 使 用 的 是 简单 的 客户 端 ， 如 
cURL， 在 获取 数据 之 前 一 定 要 先 验证 状态 码 。 如 果 自 己 编写 API 客户 端 ， 首 先 要 重点 关 
注 状 态 码 。 刚 开始 使 用 GitHub API 的 用 户 应 该 仔细 检查 响应 的 状态 码 ， 熟 悉 请 求 可 能 致 错 
的 各 种 状况 。 











1.7.1 成 功 〈200 或 201) 

只 要 你 用 过 HTTP 客户 端 ， 就 知道 HTTP 状态 码 “200” 表 示 成 功 。 请 求 的 目标 地 址 和 相 
关 的 参数 正确 时 ，GiHub 响应 的 状态 到 是 200。 如 果 请 求 在 服务 器 中 创建 内 容 ， 响 应 的 状 
态 码 是 201， 表 示 成 功 在 服务 器 中 创建 了 内 容 。 























$ curl -s -i https://api.github.com | grep Status 
Status: 200 OK 


1.7.2 不 合 规 的 JSON (400) 
如 果 载 荷 (请 求 中 发 送 的 JSON) 无 效 ，GitHub API 的 响应 是 400 错误 ， 如 下 所 示 : 


$ curL -i -uy xrd -d 'yaml: true' -X POST https://api.github.com/gists 
Enter host password for user 'xrd': 

HTTP/1.1 400 Bad Request 

Server: GitHuyub.com 

Date: Thu, 04 Jun 2015 20:33:49 GMT 

Content-Type: application/json; charset=utf-8 





Content-Length: 148 
Status: 400 Bad Request 


{ 
"message": "Problems parsing JSON", 
"documentation_url": 
"https://developer .github.com/v3/o0auth_authorizations/#create...authorization" 


上 





这 里 ， 我 们 打算 使 用 Gist API 文档 (https://developer.github.com/v3/gists/#create-a-gist) 中 
给 出 的 端点 新 建 一 个 Gist。 后 面 有 一 章 会 详细 讨论 Gist。 这 个 请 求 失败 了 ， 因 为 我 们 使 用 
的 不 是 JSON (看 起 来 使 用 的 像 是 YAML， 参 见 第 6 章 )。 载 和 荷 使 用 -d 开关 发 送 。GitHub 
在 返回 的 JSON 响应 中 使 用 documentation_url 键 提 供 了 一 个 地 址 ， 告 诉 你 在 哪里 寻找 正 
确 格式 的 文档 。 注 意 ， 我 们 使 用 了 -X 开关 并 把 值 设 为 PoST， 这 么 做 是 为 了 告诉 cURL 向 
GitHub 发 起 POST 请 求 。 


















































1.7.3 错误 的 JSON (422) 


如 果 请 求 中 有 任何 无 效 的 字段 ，GitHub 会 响应 422 错误 。 下 面 我 们 尝试 修复 前 面 那 个 请 
求 。 根 据 文档 ，JSON 载荷 应 该 使 用 下 述 格式 : 
































{ 
"description": "the description for this gist", 
"public": true, 
"files": { 
"filel.txt’s 六 
"content": "String file contents" 
} 
} 
} 


如 果 JSON 是 有 效 的 ， 但 是 字段 不 正确 呢 ? 


$ curl -i -uyu chris@burningon.com -d '{ "a" : "b" }' -XxX POST 
https://api.github.com/gists 

Enter host password for User 'chris@burningon.com’': 
HTTP/1.1 422 Unprocessable Entity 


{ 
"message": "Invalid request.\n\n\"files\" wasn't supplied.", 
"documentation_url": "https://developer.github.com/v3" 


lL 


注意 两 件 事 。 其 一 ， 返 回 的 是 422 错误 ， 表 示 JSON 有 效 ， 但 是 字段 不 正确 。 其 二 ， 获 得 
一 个 说 明 错 误 原 因 的 响应 : 请 求 载荷 中 缺少 files 键 。 
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1.7.4 成功 创建 (201) 
我 们 已 经 知道 JSON 无 效 时 会 发 生 什么 ， 那么 如 果 请 求 发 送 的 JSON 是 有 效 的 呢 ? 


$ curl -i -yu xrd \ 

-d '{"description":"A","public":true,"files":{"a.txt":{"content":"B"}}} \ 
https://api.github.com/gists 

Enter host password for user 'xrd': 

HTTP/1.1 201 Created 


"url": "https://api.github.com/gists/4a86ed1ica6f289d0f6a4"， 
"forks_url": 
"https://api.github.com/gists/4a86ed1ica6f289d0f6a4/forks", 
"commits_url": 
"https://api.github.com/gists/4a86ed1ica6f289d0f6a4/commits", 

"id": "4a86ed1ica6f289d0f6a4"， 

"git_ pull_url": "https://gist.github.com/4a86ed1ica6f289d0f6a4.git", 


ee 
成 功 ! 我 们 创建 了 一 个 Gist， 而 且 获 得 了 表示 正确 处 理 的 201 状态 码 。 为 了 让 命令 更 易于 


阅读 ， 我 们 使 用 反 斜 线 ， 把 参数 写成 多 行 。 此 外 ， 注 意 JSON 不 需要 空格 ， 因 此 我 们 把 传 
给 -d 开关 的 字符 串 中 的 空格 全 都 去 掉 了 (为 了 节省 空间 ， 让 命令 更 容易 阅读 一 些 ) 。 





1.7.5 “完全 没 变 化 〈304) 
304 与 200 的 作用 类 似 : 告诉 客户 端 请 求 成 功 。 不 过 ，304 多 提供 了 一 些 信 息 ， 告 诉 客 户 
端 自 上 次 请 求 以 来 数据 没有 变化 。 对 于 担心 用 量 限 制 的 用 户 来 说 (大 多 数 用 户 都 会 担心 )， 
这 是 重要 的 信息 。 我 们 还 未 讲解 频率 限制 的 运作 方式 ， 所 以 下 面 先 讨论 这 个 话题 ， 然 后 再 
演示 如 何 使 用 条 件 首部 触发 304 响应 码 。 
































1.7.6 ”GitHub API 的 频率 限制 

GitHub 会 设法 限制 用 户 请 求 API 的 频率 。 匿 名 请 求 (没有 使 用 用 户 名 和 密码 或 者 OAuth 
令 牌 验证 身份 的 请 求 ) 的 限制 为 一 小 时 60 次 。 如 果 开 发 一 个 与 GitHub API 集成 的 系统 ， 
代表 用 户 执行 操作 ， 一 小 时 60 次 请 求 显 然 不 够 用 。 





验证 身份 后 ， 向 GitHub API 发 起 请 求 的 频率 会 增加 到 每 小 时 5000 次 。 虽 然 这 比 匿名 请 求 
的 频率 多 了 两 个 数量 级 ， 但 是 若 想 使 用 你 自己 的 GitHub 凭据 代表 很 多 用 户 发 起 请 求 ， 仍 
然 有 问题 。 





鉴于 此 ， 如 果 你 的 网 站 或 服务 使 用 GitHub API 请 求 GitHub API 中 的 信息 ， 应 该 考虑 使 用 
OAuth， 并 且 使 用 用 户 共享 的 身份 验证 信息 请 求 GitHub API。 如 果 使 用 其 他 用 户 的 GitHub 




















账户 的 令 牌 ， 那 么 频率 限制 算 在 该 用 户 身上 ， 而 不 是 算 在 你 的 账户 上 。 














其 实 ， 频 率 限制 有 两 种 :核心 频率 限制 和 搜索 频率 限制 。 前 面 几 段 说 明 的 是 
核心 频率 限制 。 对 搜索 来 说 ， 验 证 身份 的 用 户 每 分 钟 不 能 发 起 超过 20 个 请 
求 ， 匿 名 用 户 每 分 钟 不 能 超过 5 个 请 求 。 这 里 假定 搜索 请 求 消 耗 的 基础 设施 
资源 更 多 ， 因 此 对 用 量 的 限制 更 严格 。 






































注意 ，GitHub 按 IP 地 址 记录 匿名 请 求 。 因 此 ， 如 果 你 身 处 防火 墙 后 
起 匿名 请 求 ， 那 么 所 有 这 些 请 求 会 算 在 一 起 。 


1.7.7 ”获知 频率 限制 

获知 频率 限制 的 方法 很 简单 ， 向 /rate_Limit 发 起 GET 请 求 即 可 。 返 回 的 JSON 文档 中 有 
要 遵守 的 频率 限制 、 剩 余 的 请 求 数 和 时 间 戳 (1970 年 之 后 的 秒 数 )。 注 意 ， 时 间 戳 的 时 区 
是 UTC (Coordinated Universal Time， 协 调 世 界 时 )。 


硬 ， 还 有 其 他 用 户 发 











下 述 命令 清单 使 用 cURL 获取 匿名 请 求 的 频率 限制 。 为 了 市 省 空间 ， 部 分 响应 省 略 了 ， 不 
过 你 能 注意 到 配额 信息 出 现 了 两 次 : 一 次 在 HTTP 响应 的 首部 中 ， 一 次 在 JSON 响应 中 。 
每 次 请 求 GitHub API 都 会 返回 频率 限制 首部 ， 因 此 不 太 有 必要 直接 请 求 /rate_Limit: 











$ curl https://api.github.com/rate_limit 


{ 
"resources": { 
"core": { 
"limit": 60， 
"remaining": 48, 
"reset": 1433398160 
]， 
"search": { 
"limit": 10， 
"remaining": 10， 
"reset": 1433395543 
} 
}, 
"rate": { 
"limit": 60， 
"remaining": 48, 
"reset": 1433398160 
} 
} 




















一 小 时 60 次 请 求 不 是 特别 多 ， 如 果 计划 做 些 有 趣 的 事 ， 可 能 很 快 就 会 超出 这 一 限制 。 如 
果 每 分 钟 60 次 请 求 的 限制 快 到 了 ， 你 可 能 要 想 办 法 验证 身份 ， 然 后 再 请 求 GitHub API。 
讨论 身份 验证 请 求 时 会 说 明 做 法 。 


对 /rate_linmit 的 请 求 算 在 频率 限制 内 。 记 住 ， 频 率 限 制 在 24 小 时 后 重 置 。 
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1.8 使 用 条 件 请 求 规避 频率 限制 

如 果 请 求 GitHub API 的 目的 是 获悉 一 个 用 户 或 一 个 仓库 的 活动 数据 ， 很 有 可 能 不 会 返回 大 
多 数据 。 如 果 每 隔 几 分 钟 检查 有 没有 新 活动 ， 在 一 段 时 间 内 可 能 没有 任何 活动 。 这 种 桂 久 
轮 询 虽然 有 时 不 传送 新 活动 ， 但 是 仍然 消耗 着 请 求 的 频率 限制 





此 时 ， 可 以 发 送 If-Modified-Since 和 If-None-Match 两 个 HTTP 条 件 首部 ， 让 GitHub 返 
回 表示 什么 都 没 变 的 HTTP 304 响应 码 。 如 果 发 送 的 请 求 包含 条 件 首 部 ， 而 且 GitHub API 
返回 HTTP 304 响应 码 ， 这 样 的 请 求 不 会 从 频率 限制 中 扣除 。 



































下 述 命令 清单 举例 说 明 如 何 把 If-Modified-Since 首部 传 给 GitHub API。 这 里 我 们 指明 ， 
仅 当 Twitter Bootstrap 仓库 在 2013 年 8 月 11 日 (星期 日 ) 下 午 7: 49 (GMT) 之 后 有 变 
化 才 接 收 内 容 。GitHub API 啊 应 的 状态 码 是 304， 而 且 告 诉 我 们 ， 仓 库 的 最 后 一 次 变动 是 
在 截止 时 间 的 前 一 分 钟 。 























$ curl -i https://api.github.com/repos/twbs/bootstrap \ 
-H "If-Modified-Since: Sun, 11 Aug 2013 19:48:59 GMT" 

HTTP/1.1 304 Not Modified 

Server: GitHuyub.com 

Date: Sun, 11 Aug 2013 20:11:26 GMT 

Status: 304 Not Modified 

X-RateLimit-Limit: 60 

X-RateLimit-Remaining: 46 

X-RateLimit-Reset: 1376255215 

Cache-ControL: public, max-age=60, s-maxage=60 

Last-Modified: Sun, 11 Aug 2013 19:48:39 GMT 














GitHub API 也 能 理解 HTTP 缓存 标签 。ETag (Entity Tag) 是 一 个 HTTP 首部 ， 用 于 确定 
之 前 缓存 的 内 容 是 否 为 最 新 版 。 系 统 可 能 会 像 下 面 这 样 使 用 ETag。 








。 客户 端 从 HTTP 服务 器 中 请 求 信息 。 
。 服务 器 返回 一 个 ETag 首部 ， 标 记 内 容 的 一 个 版 本 。 
。 客户 端 在 后 续 的 所 有 请 求 中 发 送 这 个 ETag 首部 : 
4 如 果 服 务 器 有 较 新 的 版 本 ， 返 回 新 内 容 和 新 ETag; 
* 如 果 服 务 器 没有 较 新 的 版 本 ,返回 HTTP 304 响应 码 。 











下 述 命令 清单 演示 两 个 命令 。 第 一 个 cURL 命令 访问 GitHub API， 生 成 ETag 值 ， 第 二 个 
命令 在 If-None-Match 首部 中 传送 那个 ETag 值 。 你 能 注意 到 ， 第 二 个 响应 是 HTTP 304， 
即 告 知 调用 方 没 有 新 内 容 。 





$ curl -i https://api.github.com/repos/twbs/bootstrap 
HTTP/1.1 200 OK 

Cache-Control: public, max-age=60, s-maxage=60 
Last-Modified: Sun, 11 Aug 2013 20:25:37 GMT 

ETag: "462c74009317cf64560b8e395b9dQcdd" 
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{ 
"id": 2126244， 
"Name": "bootstrap", 
"full_name": "twbs/bootstrap", 


i 


$ curl -i https://api.github.com/repos/twbs/bootstrap \ 
-H 'If-None-Match: "462c74009317cf64560b8e395b9dQcdd"' 


HTTP/1.1 304 Not Modified 

Status: 304 Not Modified 

Cache-ControL: public, max-age=60, s-maxage=60 
Last-Modified: Sun, 11 Aug 2013 20:25:37 GMT 
ETag: "462c74009317cf64560b8e395b9dQcdd" 


建议 你 使 用 条 件 请 求 首部 ， 这 样 能 节省 资源 ， 还 能 确保 支持 GitHub API 的 基础 设施 不 生成 
不 必要 的 内 容 。 








目前 ， 我 们 都 使 用 cURL 客户 端 访问 GitHub API， 只 要 网 络 人 允许， 我 们 可 以 做 任何 想 做 的 
事 。 此外，GitHub API 还 能 使 用 其 他 方式 访问 ， 例 如 使 用 浏览 器 ， 不 过 此 时 有 些 特定 的 限 
制 ， 讨 论 如 下 。 


1.9 在 Web 中 访问 内 容 


如 果 使 用 服务 器 端 程序 或 者 命令 行 访问 GitHub API， 只 要 网 络 人 允许， 可 以 发 起 任何 请 求 。 
如 果 想 在 浏览 器 中 使 用 JavaScript 和 XHR (XmlHttpRequest) 对 象 访 问 GitHub API， 要 知 
道 浏览 器 同 源 策略 施加 的 限制 。 简 单 来 说 ， 在 JavaScript 中 ， 不 能 使 用 标准 的 XHR 请 求 访 
问 源 页 面 所 在 域名 之 外 的 域名 。 若 想 绕 开 这 个 限制 ， 有 两 个 选择 ， 一 个 很 巧妙 (JSON-P)， 
另 一 个 支持 全 面 ， 但 是 稍微 麻烦 点 (CORS)。 








出 叫 


























1.9.1 JSON-P 


JSON-P 算是 一 种 浏览 器 hack， 目 的 是 避 开 同 源 策略 ， 获 取 其 他 服务 器 中 的 信息 。JSON-P 
之 所 以 可 用 ， 是 因为 同 产 策略 不 检查 <script> 标签 ， 也 就 是 说 ， 页 面 可 以 从 源 服务 器 之 外 
的 服务 器 中 引用 内 容 。JSON-P 的 用 法 是 ， 在 JavaScript 文件 中 使 用 特殊 的 方式 编码 载 符 数 
据 ， 将 其 载 入 自己 实现 的 回调 函数 中 处 理 。GitHub API 支持 这 种 句法 : 请求 脚 本 时 为 URL 
提供 一 个 参数 ， 指 明 加 载 完 脚本 后 执行 哪个 回调 。 


在 cURL 中 可 以 模拟 这 样 的 请 求 : 






































$ curl https://api.github.com/?caLLback=myCaLLback 
/**/myCallback({ 
"meta": { 
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"X-RateLimit-Limit": "60", 

"X-RateLimit-Remaining": "52", 

"X-RateLimit-Reset": "1433461950 " ， 

"Cache-Control": "public, max-age=60, s-maxage=60", 
"Vary": "Accept", 

"ETag": "\"a5c656a9399ccd6b44e2f9a4291c8289\""， 
"X-GitHub-Media-Type": "github.v3", 

"status": 200 


"data": { 
"current_user_url": "https://api.github.com/user", 
"current_uyser_authorizations_html_url": 
"https://github.com/settings/connections/applications{/client id}", 
"authorizations_url": "https://api.github.com/authorizations", 


es 
}) 





如 果 在 网 页 中 的 <script> 标签 里 使 用 上 述 代 码 中 的 URL (<script src="https://api. 
github.com/?callback=myCallback"” type= "text/javascript"></script>)， 浏览 器 会 加 载 
上 述 代 码 中 的 内 容 ， 把 数据 传 给 你 定义 的 myCaLLback 回调 函数 执行 。 在 网 页 中 可 以 像 下 面 
这 样 实现 回调 函数 : 




















<script> 
function myCallback( payload ) { 
if( 200 == payload.status ) { 
document.getElementById("success").innerHTML = 
payload.data.current_user_url; 
} else { 
document .getELementById("error") .innerHTML = 
"An error occurred " ; 
} 
} 


</script> 





这 个 示例 演示 如 何 从 载荷 数 据 中 获取 current_user_urt， 把 它 放 入 一 个 div 元 素 ， 例 如 


<div id="success"> </div>。 








JSON-P 通过 <script> 标签 实现 ， 因 此 只 支持 向 API 发 起 GET 请 求 。 如 果 只 需要 API 的 
只 读 权限 ， 多 数 情 况 下 JSON-P 能 满足 需求 ， 而 且 易 于 配置 。 


如 果 你 觉得 JSON-P 局 限 太 多 或 者 不 优雅 ， 可 以 使 用 CORS。 这 是 在 网 页 中 访问 外 部 服务 
的 官方 方式 ， 不 过 较 复 杂 。 





1.9.2 CORS 支 持 
CORS 用 于 从 源 主机 之 外 的 域名 中 访问 内 容 ， 这 是 W3C (一 个 Web 标准 组 织 ) 认可 的 
方式 。CORS 要 求 事先 正确 配置 服务 器 ， 查 询 时 必须 表明 自己 允许 跨 域 请 求 。 如 果 服 














务 器 明确 表示 ,“ 是 的 ， 你 可 以 从 其 他 域名 中 访问 我 的 内 容 "， 那 么 就 允许 CORS 请 求 。 
HTML5Rocks 网 站 中 有 篇 优秀 的 教程 (http:/www.html5rocks.com/en/tutorials/cors/)， 解 说 
了 CORS 的 诸多 细节 。 


因为 使 用 CORS 的 XHR 支持 从 同一 域名 获取 的 同类 XHR 请 求 ， 所 以 除了 GET 请 求 之 外 ， 
还 能 向 GitHub API 发 起 POST、DELETE 和 UPDATE 请 求 。JSON-P 和 CORS 是 在 Web 
浏览 器 中 访问 GitHub API 的 两 种 方式 ， 前 者 简单 ， 后 者 强大 ,但 是 需要 额外 配置 。 








我 们 可 以 使 用 cURL 证 明 GitHub API 能 正确 响应 CORS 请 求 。 这 里 我 们 只 关注 首部 ， 因 
此 要 使 用 -I 开关 ，i cURL 发 起 HEAD 请 求 ， 告 诉 服务 器 别 响 应 主体 内 容 。 








curl -I https://api.github.com 
HTTP/1.1 200 OK 
Server: QiLtHub .com 


X-Frame-Options: deny 

Content-Security-Policy: default-src "none' 
Access-Control-Allow-Credentials: true 
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, 
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, 
X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval 
Access-Control-Allow-Origin: * 

X-GitHub-Request-Id: COF1CF9E:07AD:3C493B:557107C7 
Strict-Transport-Security: max-age=31536000; includeSubdomains; 
preload 


可 以 看 到 ，Access-ControL-ALLow-Credentials 首部 的 值 是 true。 有 些 JavaScript 宿主 浏 
览 器 会 自动 发 起 预 检 (preflight) 请 求 ， 验 证 这 个 首部 的 值 是 否 为 true (此 外 还 会 验证 
Access-ControL-ALLow-0rigin 等 其 他 首部 是 否 正确 设置 ， 以 便 人 允许 处 理 来 自 相 应 域 的 请 
求 ) ;有些 浏览 器 则 要 求 我 们 自己 动手 发 起 预 检 请 求 。 自 动 预 检 还 是 手动 预 检 由 浏览 器 
的 实现 决定 。 浏 览 器 通过 这 些 首部 确认 支持 CORS 后 ， 可 以 向 GitHub API 所 在 的 域 发 起 
XHR 请 求 ， 这 与 向 相同 的 域 发 起 的 任何 其 他 XHR 请 求 没有 差别 。 




















我 们 大 致 讲解 了 如 何 连接 GitHub API， 以 及 GitHub API 的 细节 。 此 外 ，GitHub API 还 有 
一 些 其 他 用 途 ， 例 如 使 用 这 项 服务 按 需 泻 染 内 容 。 


1.9.3 ”指定 响应 的 内 容 格式 

向 GitHub API 发 送 请 求 时 可 以 指定 期 望 的 响应 格式 。 比 方 说 ， 如 果 请 求 的 内 容 包 含 提交 
评论 中 的 文本 ， 可 以 使 用 Accept 首部 指定 获取 原始 的 Markdown 还 是 Markdown 生成 的 
HTML。 此 外 ， 还 可 以 指定 使 用 GitHub API 的 哪个 版 本 。 当 下 ， 可 以 指定 使 用 API 的 第 3 
版 或 beta 版 。 
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获取 格式 化 内 容 
随 请 求 发 送 的 Accept 首部 可 以 影响 GitHub API 返回 的 文本 格式 。 下 面 举 个 例子 。 假 设 你 
想 读 取 一 个 GitHub 工 单 的 正文 。 工 单 的 正文 以 Markdown 格式 存储 ， 默 认 作为 请 求 的 响应 
返回 。 如 果 想 使 用 HTML 演 染 响应 而 不 是 Markdown， 可 以 发 不 同 的 Accept 首部 ， 如 下 述 
cURL 命令 所 示 : 




















$ URL= 'https://api.github.com/repos/raiLs/raiLs/issues/11819 
$ curl -s SURL | jq '.body' 


"Hi, \r\n\r\nI have a problem with strong...." © 
$ curl -s SURL | jq '.body_html' 
null 名 


$ curl -s SURL \ 
-H "Accept: application/vnd.github.html+json" | jq '.body_html’ 
"<p>Hi, </p>\n\n<p>I have a probLem with..." © 


@ 没有 指定 额外 的 首部 ， 获 取 数 据 的 内 在 表述 ， 即 Markdown。 
@ 注意 ， 如 果 不 请 求 HTML 表示 ， 默 认 情 况 下 JSON 响应 中 就 没有 HIML 格式 内 容 。 
@ 如 果 像 第 三 个 命令 那样 指定 Accept 首部 ，JSON 啊 应 中 会 包含 泻 染 成 HTML 的 正文 。 




















除了 “raw” 和 “html” 之 外 ， 还 有 两 个 格式 选项 会 影响 GitHub API 分 发 Markdown 内 容 
的 方式 。 如 果 把 格式 指定 为 “text”， 工 单 的 正文 会 以 纯 文本 格式 返回 。 如 果 指 定 为 “full”， 
内 容 会 经 过 多 次 演 染 ， 包 括 原 始 的 Markdown、 演 染 后 的 HTML 和 演 染 后 的 纯 文本 。 








除了 控制 文本 内 容 的 格式 之 外 ， 获 取 blob 时 还 可 以 指定 返回 原始 的 二 进 制 文件 还 是 base64 
编码 的 文本 。 获 取 提 交 时 ， 还 可 以 指定 返回 内 容 的 dif 格式 还 是 patch 格式 。 精 确 控制 格 
式 的 详细 信息 参见 GitHub API 的 文档 。 








GitHub 团队 为 API 提供 了 非常 详细 的 文档 ， 包 含 使 用 cURL 的 示例 。 建 议 收 
藏 这 个 URL: https:/developer.github.com/v3/， 你 经 常会 用 到 。 注 意 ， 这 个 
URL 显然 是 针对 当前 的 第 3 版 API， 因 此 有 新 版 发 布 的 话 ，URL 会 变 。 











1.10 “小 结 


我 们 在 本 章 学 习 了 如 何 使 用 最 简单 的 客户 端 〈 即 命令 行 HITP 工具 cURL) 访问 GitHub 
API。 此 外 ， 我 们 通过 分 析 JSON 响应 ， 探 索 了 GitHub API， 还 说 明了 如 何 结合 使 用 cURL 
和 命令 行 工 具 (jq)， 在 往往 包含 大 量 数据 的 GitHub API 响应 中 快速 查找 信息 。 我 们 学 习 
了 GitHub 支持 的 不 同 身份 验证 机 制 ， 还 学 习 了 在 浏览 器 中 访问 GitHub API 的 可 行 性 和 折 
中 方案 。 


下 一 章 说 明 Gist 和 Gist API。 我 们 将 使 用 Ruby 构建 一 个 显示 Gist 的 程序 ， 把 应 用 的 所 有 
源码 文件 都 放 在 Gist 中 。 
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GitHub 满足 了 程序 员 分 享 信息 的 热切 期 队 ， 为 软件 开发 带 来 了 变革 。 但 是 GitHub 不 仅仅 
是 个 “分 享 ” 工 具 ， 而 且 是 众多 工具 的 集合 ， 这 些 工具 去 除了 沟通 障碍 ， 简 化 了 工作 流 
程 。 这 些 工具 的 出 现 恰 着 信息 技术 发 生变 划 之 时 ， 在 新 形式 下 公司 越 来 越 多 地 采用 助力 远 
程 工作 的 开放 技术 。 


Gist 服务 部 分 满足 了 这 种 需求 。 使 用 Gist 可 以 私下 分 享 和 重用 代码 以 及 重 构 代码 ， 还 能 以 
之 前 的 重量 级 工具 不 能 提供 的 方式 进行 试验 。 本 章 探 讨 如 何 使 用 Gist 分享 代码 ， 然 后 使 用 
Gist API 构建 一 个 托管 在 Gist 中 的 应 用 。 


2.1 简便 的 代码 分 享 工 具 


创建 Gist 的 方法 很 简单 ， 在 页 面 中 部 那个 大 大 的 文本 框 中 粘贴 代码 片段 ， 选 择 性 输入 描述 
或 文件 名 ， 然 后 选择 创建 公开 或 秘密 Gist 即 可 。Gist 创建 好 之 后 会 给 你 提供 一 个 URL， 用 
于 分 享 。 大 多 数 情况 下 ，Gist 能 自动 检测 代码 的 语言 ， 然 后 根据 语言 高 之 显示 句法 ， 如 图 
2-1 所 示 。 
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2-1: 在 Gist 中 编写 JSON 


其 他 服务 也 能 做 到 这 一 点 : 首先 是 Pastebin， 还 有 其 他 众多 提供 差异 化 代码 分 享 服务 的 网 


。 可 是 ，GitHub 提供 的 Gist 不 仅仅 是 一 项 代码 粘贴 服务 。Gist 是 强大 的 仓库 ， 可 派生 ， 
编辑 ， 功 能 全 面 。 接 下 来 我 们 将 介绍 一 些 基础 知识 ,说明 Gist 是 什么 ， 如 何 创建 Gist， 
后 指出 ， 除 了 分 享 代码 之 外 ，Gist 还 是 一 个 实 实在 在 的 应 用 。 


.2 ”Gist 是 仓库 


个 Gist 都 是 微型 仓库 ， 可 以 更 新 ， 可 以 使 用 git log 命令 查看 历史 ， 可 以 下 载 、 修 改 之 
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再 使 用 git push 命令 推送 到 gist.github.com 中 的 仓库 (这 会 在 该 公共 网 页 中 重新 发 布 
st)。 些 外，Gist 与 常规 的 仓库 一 样 ， 可 以 派生 。 














Gist 仓库 中 可 以 创建 分 支 ， 不 过 gist.github.com/ 中 不 会 显示 分 支 。 尽 管 如 此 ， 如 果 需 要 
用 分 支 ， 仍然 可 以 像 往 常 一 样 在 仓库 中 创建 分 支 。 推 送 之 后 ,分支 信息 会 保存 在 上 游 仓 
中 。 
开 和 秘密 Gist 的 数量 不 限 。 多 数 情况 下 ， 可 以 用 秘密 Gist 代替 私有 人 仓库， 而且 秘 密 Gist 
算 在 GitHub 付费 账户 对 私有 仓库 的 数量 限制 内 。 你 也 可 以 将 Gist 公开 ， 然 后 把 URL 分 
到 邮件 列表 或 你 想得到 公众 反馈 的 其 他 地 方 。 














Gist 分 为 两 种 (公开 的 和 秘密 的 )， 理 解 二 者 之 间 的 区 别 很 重要 。 公 开 Gist 
能 搜索 到 。 秘 密 Gist 搜索 不 到 ， 但 是 只 要 知道 URL 就 能 访问 。 不 要 在 Gist 
中 发 布 任何 机 密 代码 ， 因 为 一 旦 发 布 ， 只 有 URL 不 为 人 知 ， 代 码 才 安全 。 














大 多 数 人 使 用 URL 分 享 Gist， 不 过 Gist 也 可 以 答 入 其 他 页 面 (如 博客 )， 以 简单 而 精美 的 
方式 显示 代码 片段 。 


2.2.1 在 HTML 中 骨 入 Gist 


如 果 想 把 Gist 戏 入 HTML 页 面 ,在 Gist 左边 寻找 “Embed” 框 ， 复 制 框 里 的 代码 (如 
<script src="https://gist.github.com/xrd/8923697.js"></script>)， 然 后 将 其 粘贴 到 
HTML 中 。 




















如 果 只 想 租 入 Gist 中 某 个 特定 的 文件 〈 前 提 是 Gist 包含 多 个 文件 )， 在 src 属性 中 URL 的 
末尾 加 上 ?fiLe=hi.rb。 


2.2.2 ”在 Jekyll 博 客 中 其 入 Gist 


在 Jekyll 博客 (参见 第 6 章 ) 中 可 以 使 用 一 个 特殊 的 句法 轻易 赔 入 Gist。{% gist 8138797 
%]} 这 个 简洁 的 句法 用 于 嵌入 公开 Gist， 地 址 是 http://gist.github.com/8138797。 如 果 想 使 
用 Gist 中 的 某 个 文件 ， 在 Gist 编号 后 添加 一 个 文件 名 ， 如 { gist 8138797 hi.rb 。 秘 
密 Gist 也 能 对 入， 此 时 要 在 前 面 加 上 Gist 所 属 账户 的 用 户 名 ， 例 如 {% gist xrd/8138797 
hi.rb %}。 














接 下 来 说 明 脱 离 GitHub.com 网 站 ， 如 何 使 用 命令 行 创建 Gist。 


2.3 ”使 用 命令 行 创建 Gist 


执行 gem install gist 命令 ， 安 装 一 个 命令 行 工具 ， 用 于 协助 创建 Gist。 这 个 工具 的 用 法 
简单 ， 输 入 命令 ， 然 后 输入 想 发 布 为 Gist 的 数据 即 可 : 


$ gist 

(type a gist. <ctrl-c> to cancel, <ctrl-d> when done) 
长 Wp : Wt. } 

https://gist.github.com/9106765 








gist 命令 会 返回 刚 创建 的 Gist 的 链接 。 默 认 ，Gist 以 匿名 方式 创建 。 如 果 想 登录 ， 要 使 用 
--Llogin 开关 。 登 录 后 ， 创 建 的 Gist 会 与 账户 关联 起 来 : 





$ gist --Login 
Obtaining OAuth2 access_token from github. 
GitHub username: xrd 
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GitHub password : 
2-factor auth code: 787878 


Success! https://github.com/settings/applications 
我 们 可 以 通过 管道 把 文件 的 内 容 传 给 gist 命令 : 


$ echo '{ "foo" : "bar" }' | gist 
https://gist.github.com/9106799 


还 可 以 使 用 cat 命令 把 文件 传 给 gist 命 


$ cat MyJavaFile.java | gist 
https://gist.github.com/9345609 


Gist 通常 用 于 显示 好 玩 或 出 错 的 代码 ， 有 时 你 并 不 想 显 示 文 件 的 全 部 内 容 。 此 时 ， 可 以 使 
A grep 能 搜索 特定 的 代码 段 ， 与 正确 的 开关 结合 后 能 把 代码 段 和 前 后 几 

行 代 码 发 布 到 Gist 中 。 下 述 命令 在 MyJavaFile.java 文件 中 搜索 myFunction 函数 ， 然 后 获 
i 20 行 代码 ， 将 其 存 入 一 个 Gist: 





$ grep -A 20 myFunction MyJavaFile.java | gist 
https://gist.github.com/9453069 


添加 -o 开关 后 ， 会 在 默认 的 Web 浏览 嚣 中 打开 Gist。 此 外 ， 可 以 使 用 -< 开关 把 Gist 的 
URL 复制 到 剪贴 板 ， 或 者 使 用 -P 开关 把 剪贴 板 中 的 内 容 复制 到 Gist 里 。 


gist 命令 还 有 很 多 其 他 有 趣 的 功能 ， 若 想 深 入 了 解 ， 执 行 gist 命令 时 指定 - -hetp 开关 。 


Gist 本 身 是 仓库 ， 因 此 有 两 种 用 途 : 一 是 托管 代码 示例 ， 二 是 作为 仓库 ， 在 里 面 存 储 功能 
完整 的 示例 应 用 。 


2.4 _Gist 是 功能 完整 的 应 用 


下 面 我 们 构建 一 个 简单 的 Sinatra 应 用 ， 以 此 说 明 托管 在 Gist 中 的 代码 也 是 真实 可 用 的 应 
用 。Sinatra 是 一 个 Ruby 库 ， 用 于 创建 特别 简单 的 Web 服务 器 。Sinatra 程序 可 以 像 下 卫 
样 简单 ; 


















































| 这 








require 'sinatra' 
get '/hi' do 


"Hello World!" 
end 


访问 gist.github.com， 创 建 一 个 Gist。 正 确 输入 上 述 代码 ， 然 后 选择 公开 Gist。 





现在 ， 我 们 创建 了 一 个 便于 分 享 的 Gist， 任 何人 都 能 查看 里 面 的 代码 。 更 重要 的 是 ， 这 是 


























一 个 存 有 可 执行 代码 的 仓库 。 如 果 想 克隆 这 个 Gist， 在 右边 寻找 Clone URL。 你 应 该 会 
到 一 个 Git 协议 的 URL 和 一 个 HTTPS 协议 的 URL。 如 果 克 隆 的 目的 只 是 读 取 Gist， 可 
以 使 用 HTTPS 协议 的 URL。 严 格 来 说 ， 使 用 HTTPS 协议 的 URL 克隆 仓库 后 ， 可 以 推送 
改动 ， 不 过 启用 双重 身份 验证 后 则 不 行 。 大 多 数 情况 下 ， 使 用 Git 协议 的 URL 更 简单 也 
更 灵活 。 


我 们 来 克隆 这 个 Gist: 











$ git clone git@gist.github.com:8138797.git 





| 





AAA 


克隆 完成 之 后 ， 进 入 仓库 。 你 会 看 到 一 组 文件 ， 目 前 这 个 仓库 中 只 有 一 个 文件 : 





$ cd 8138797 
$ ls 
hi.rb 


这 个 代码 可 以 执行 ， 运 行 的 方式 是 执行 ruby hi.rb 命令 。 

如 果 以 前 没 用 过 Sinatra， 执 行 上 述 命令 后 会 报错 。 这 个 程序 需要 一 个 名 为 “sinatra” 的 库 ， 
而 我 们 还 没 安装 那个 库 。 我 们 可 以 编写 一 个 自述 文件 ， 或 者 在 那个 文件 中 添加 文档 。 保 证 
用 户 正确 安装 所 需 库 的 另 一 个 方法 是 使 用 Gemfile 文件 。 这 个 文件 用 于 指定 需要 安装 哪些 
库 ， 以 及 从 哪里 安装 。 听 起 来 这 是 最 好 的 方式 。 





























$ printf "source 'https://rubygems.org'\ngem 'sinatra'" > Gemfile 














bundle 命令 (由 bundler gem 提供 ) 会 安装 Sinatra 及 相关 的 依赖 : 


$ bundle 

Using rack (1.5.2) 

Using rack-protection (1.5.1) 

Using tilt (1.4.1) 

Using sinatra (1.4.4) 

Using bundler (1.3.5) 

Your bundle is complete! 

Use ‘bundle show [gemname]. to see where a bundled gem is installed. 


为 什么 要 这 么 做 呢 ?” 因 为 现在 我 们 可 以 在 本 地 仓库 中 添加 Gemfile 文件 ， 然 后 发 布 到 Gist 
中 ， 在 网 上 分 享 。 现 在， 我 们 的 仓库 中 不 仅 有 代码 ， 还 有 为 人 熟知 的 清单 文件 ， 指 明 运 行 
代码 所 需 的 组 人 








I 





o 


me ~ a a 
2.5 泻 染 Gist 的 Gist 
下 面 把 Octokit 这 个 Ruby gem 添加 到 应 用 中 ， 用 它 拉 取 指定 用 户 的 所 有 公开 Gist。Octokit 
是 访问 GitHub API 的 官方 Ruby 库 。 为 什么 要 创建 一 个 显示 其 他 Gist 的 Gist 呢 ” 如 今 流 行 
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1 





五 





自 指 的 元 代码 ， 这 是 现代 人 对 René Magritte 的 著名 画作 《这 不 是 一 个 烟斗 》 的 回应 。 
在 根 目录 中 添加 一 个 视图 文件 index.erb: 


<html> 
<body> 


User has <%= count %> public gists 


</body> 
</html> 


在 Gemfile 文件 中 添加 Octokit gem: 


gem "octokit" 





[EC 
st 
tt 


运行 bundle 安装 Octokit。 然 后 ， 把 hi.rb 应 用 改 成 下 面 ; 














require 'sinatra' 
require 'octokit' 
set :views, "." 
get '/:username' do |username| 

User = Octokit.user Username 

count = user.public gists 

erb :index, locals: { :count => count } 
end 


现在 ,文件 系统 应 该 是 下 面 这 样 ， 有 三 个 文件 : 





$ ls -1 
Gemfile 
hi.rb 
index.erb 


按 Ctrl-C 键 ， 然 后 执行 ruby hi.rb， 重 启 Sinatra。 在 浏览 器 中 访问 http://localhost:4567/ 
xrd， 你 会 看 到 xrd 用 户 公 开 Gist 的 数量 ( 见 图 2-2)。 修 改 URL 中 的 用 户 名 ， 指 定 其 他 
GitHub 账户 的 用 户 名 ， 你 会 看 到 页 面 中 显示 该 用 户 最 近 发 布 的 五 个 Gist。 


























注 1: Ben Zimmer 对 此 解说 得 最 好 (http://www.bostonglobe.com/ideas/2012/05/05/dude-this-headline-meta- 
dude-this-headline-meta/it75G5CSgqi82NtoQHIucEP/story.html?camp=pm ) 。 
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User has 49 public gists 











2-2: 显示 Gist 的 数量 


2.5.1 深入 了 解 Gist API 

GitHub API 使 用 超 媒体 ， 而 不 是 由 资源 驱动 的 简单 API。Octokit 这 样 的 客户 端 把 超 媒 体 细 
节 隐 藏 到 优雅 的 Ruby 代码 之 后 了 。 不 过 ， 理 解 超 媒体 的 工作 方式 仍 有 益处 ， 这 样 便于 深 
入 GitHub API， 获 取 更 多 的 信息 。 








大 多 数 REST 式 API 都 有 “网 站 地 图 "， 这 通常 是 一 份 API 参考 文档 ， 告 诉 用 户 该 用 哪些 
端点 。 知 道 API 提供 了 哪些 资源 之 后 ， 用 户 使 用 一 些 HTTP 动词 处 理 资源 。 超 媒体 看 待 
API 的 方式 有 所 不 同 。 超 媒体 API 在 响应 中 通过 “功能 可 见 性 ”自我 描述 。 这 句 话 是 什么 
意思 呢 ? 我 们 来 看 下 面 这 个 API 的 响应 。 




















{ 
"_ Links": { 
"self": { 
"href": "http://shop.oreilly.com/product/0636920030300.do" 
} 
} 
"id": "xrd", 
"name": "Chris Dawson" 
} 


可 以 看 出 ， 这 个 载荷 中 有 一 个 ID 〈"xrd") 和 一 个 名 字 ("Chris Dawson" )。 这 个 载 洽 根据 
HAL Primer 文档 (https://phlyrestfully.readthedocs.org/en/latest/halprimer.html) 编写 ， 那 篇 
文档 中 有 相关 概念 更 详细 的 说 明 。 


有 一 点 要 注意 : 超 媒 体 API 的 载荷 中 包含 数据 本 身 的 元 数据 ， 以 及 可 能 对 数据 执行 的 操作 
的 元 数据 。REST 式 API 往往 在 载荷 之 外 提供 映射 ， 因 此 使 用 这 种 API 时， 要 使 用 特别 的 
方式 把 API 网 站 地 图 与 数据 结合 起 来 。 而 对 超 媒 体 API 来 说 ， 客 户 端 能 以 正确 且 智 能 的 方 
式 处 理 载 街 ， 完 全 用 不 到 人 类 可 读 的 文档 中 存储 的 网 站 地 图 。 





















































这 种 松 耦 合 让 API 和 客户 端 具 有 灵活 性 。 理 论 上 ， 超 媒体 API 与 理解 超 媒体 的 客户 端 工作 
起 来 灵犀 相通 。 修 改 API 后 ， 由 于 理解 超 媒体 ， 客 户 端 能 发 现 变化 ， 继 续 按 预 期 运作 。 如 
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办 使 用 REST 式 API 的 话 ， 必 须 更 新 客户 端 (必须 安装 新 版 客户 端 )， ee， 

端 代码 。 超 媒体 API 的 后 端 可 能 发 生 改 动 ， 此 时 ， 只 要 客户 端 能 理解 超 媒体 ， 就 能 自动 且 
动态 地 确定 从 响应 中 获取 信息 的 正确 方式 。 也 就 是 说 ， 对 超 媒 体 客户 妆 We API 后 端 变 
化 时 客户 端 代码 不 需要 变 。 








《使 用 HTML5 和 Node 构建 超 媒 体 API》 一 书 对 这 个 话题 做 了 深入 阐述 。 


2.5.2 ”使 用 Octokit 获 取 超 媒体 数据 
现在 我 们 稍微 了 解 了 超 媒 体 ， 下 面 使 用 Octokit 从 中 获取 一 些 数据 。 





。 先 在 代码 中 创建 一 个 资源 ， 例 如 user = 0ctokit.user "xrd"， 以 此 初始 化 客户 端 

。 现在 user 是 一 个 对 象 ， 含 有 资源 的 真实 数据 。 在 这 人 4 个 示例 中 ， 可 以 调用 user. 
followers 方法 查看 我 寥寥 无 几 的 关注 者 数量 。 

。 user 对 象 中 还 有 超 媒 体 引 用 ， 调 用 user.rels 方法 可 以 看 到 这 些 引 用 。 这 个 方法 获取 的 
是 超 媒体 链接 中 描述 的 关系 。 

。 关系 (通过 调用 user.rels 方法 获取 ) 包括 头像 、 自 述 、 关 注 者 ， 等 等 。 

。 在 某 个 关系 上 调用 get.data 方 法 可 以 访问 并 获取 GitHub API 中 的 数据 (followers = 
user.reLs[ :foLLowers].get.data)。 


。 调用 .get.data 方法 得 到 的 是 一 个 由 关注 者 组 成 的 数组 (超过 100 个 元 素 时 分 页 )。 




















后 我 们 扩充 这 个 Sinatra 应 用 ， 使 用 超 媒体 引用 获取 关于 用 户 的 Gist 的 具体 数据 。 











require "Sinatra' 
require 'octokit' 


set :views, "." 


helpers do 
def h(text) 
Rack: :Utils.escape_html(text) 
end 
end 


get '/:username' do |username| 

gists = Octokit.gists username, :per_page => 5 

erb :index, locals: { :gists => gists, Username: Username } 
end 


index.erb 文件 中 的 代码 用 于 迭代 各 个 Gist， 获 取 Gist 的 内 容 。 可 以 看 出 ， 响 应 对 象 是 一 个 
由 Gist 组 成 的 数组 ， 每 个 元 素 都 有 一 个 名 为 fletds 的 属性 。 这 个 属性 的 值 是 各 个 Gist 中 所 
含 文件 的 文件 名 。 访 问 文件 数组 中 的 文件 名 会 得 到 一 个 超 媒体 属性 refs。 然 后 使 用 Octokit 
提供 的 .get.data 方法 获取 原始 内 容 (raw) : 




















<htmL> 
<body> 


<h2>User <%= Username %>'s Last five gists</h2> 
<% gists.each do |g| %> 

<% g[:files].fields.each do |f| %> 

<b><%= f %></b>: 


<%= h g[:files][f.to_sym].rels[:raw].get.data %> 


<br/> 
<br/> 


<% end %> 
<% end %> 


</body> 
</htmL> 


现在 ， 我 们 能 看 到 Gist 及 其 内 容 ， 如 图 2-3 所 示 。 
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User xrd's last five gists 


sample.ruby: puts "Hello" 
sample.json: { "foo" : "bar" } 
hi.rb: require 'sinatra' get /hi do "Ok then!" end 


tumblr import: ruby -rjson -rfileutils -ropen-uri -ryaml -rnokogiri -rjekyll-import -e 'Jekyllimport::Importers::Tumblr.process( { 
true, rewrite_urls: true } )' 

controller.spec.js: … var mockFirebase = mockSimpleLogin = undefined; function generate MockFirebaseSupportO { // <1> mc 
'$login': function| { return { then: function( cb ) { cb( { name: "someUser", accessToken: "abcdefghi" } ); } }; } } }; } var $tim 
generateMockFirebaseSupportO; // <2> $timeout = $injector.get( '$timeout' ); scope = $rootScope.$new(); ctrl = $controller( "G: 


'$window': prompter, '$firebase': mockFirebase, '$firebaseSimpleLogin': mockSimpleLogin } ); // <3> } )); ... 
firebase-mock .js: var Firebase = function (url) { } angular.module( 'firebase', [] ); 











2-3: 最 新 发 布 的 五 个 Gist， 带 有 详细 信息 


2.6 ”小结 








本 章 介绍 了 Gist， 学 习 了 如 何 使 用 Gist 分 享 代 码 片段 。 我 们 构建 了 一 个 简单 的 应 用 ， 将 其 

















存储 为 一 个 Gist。 这 个 应 用 首次 使 用 高 级 语言 编写 的 客户 端 库 (使 用 Ruby 编写 的 Octokit 














体 元 数据 实现 一 个 客户 端 库 。 








库 ) 从 GitHub API 中 获取 数据 。 我 们 还 深入 了 解 了 超 媒体 的 运作 方式 ， 以 及 如 何 使 用 超 媒 


下 一 章 说 明 GitHub 使 用 的 维基 库 Gollum， 还 会 介绍 用 于 访问 Git 仓库 的 Ruby 库 Rugged 








和 用 于 访问 GitHub 的 Ruby 库 。 
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GitHub 使 用 的 维基 库 Gollum 





维基 改变 了 我 们 创建 和 消化 信息 的 方式 。 维 基 对 技术 项 目 (代码 仓库 ) 是 个 很 好 的 补充 ， 
因为 不 会 添加 代码 的 非 技术 人 员 也 能 作出 贡献 。Gollum 是 GitHub 开发 的 开源 维基 库 。Git 
改变 了 协作 编辑 代码 的 方式 ，Gollum 则 把 Git 的 优势 引入 广泛 使 用 的 维基 发 布 流程 中 。 
Gollum 维基 本 身 是 仓库 ， 一 般 用 于 注解 通常 以 代码 为 中 心 的 仓库 。 通 过 GitHub 的 努力 ， 
任何 仓库 都 能 轻易 关联 一 个 维基 。 














本 章 探讨 Gollum 的 基本 用 法 。 我 们 将 在 GitHub 中 创建 一 个 维基 ， 然 后 学 习 如 何在 GitHub 
中 编辑 它 ， 以 及 如 何在 本 地 设备 中 将 其 作为 一 个 仓库 使 用 。 接 着 ， 我 们 将 自己 动手 在 命令 
行 中 创建 一 个 Gollum 维基 ， 指 出 至 少 要 有 哪些 文件 才能 算是 一 个 Gollum 人 仓库。 最后， 我 
们 将 构建 一 个 简单 的 图 像 整 理工 具 ， 以 一 种 完全 不 同 的 方式 编辑 Gollum 维基 ， 不 过 即便 
如 此 ， 仍 能 像 常规 的 Gollum 维基 那样 把 信息 发 布 到 GitHub 中 。 在 这 个 过 程 中 ， 我 们 会 稍 
微 探 讨 一 下 Git 的 内 部 机 制 。 






































本 章 会 演示 如 何 使 用 编程 的 方式 修改 Git 仓库 ， 无 需 深 入 理解 Git 的 内 部 机 
理 也 能 跟 上 节奏 。《Git 版 本 控制 管理 》 一 书 对 本 章 (以 及 后 面 几 章 ) 是 很 好 
的 补充 。 


3.1 “ 史 麦 戈 的 故事 ……” 


最 简单 的 Gollum 维基 是 只 有 一 个 文件 的 Git 仓库 ， 这 个 文件 是 Home.ext (ext 可 以 是 任何 
被 支持 的 维基 标记 格式 ， 下 文 讨论 )。 
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3.1.1 与 仓库 关联 的 


GitHub 中 的 任何 仓库 ， 不 管 











维基 





是 公开 的 还 是 私有 的 ， 都 可 以 关联 一 个 Gollum 维基 。 如 有 果 想 





图 标 ， 





创建 与 仓库 关联 的 维基 ,访问 仓库 页 面 ， 然 后 看 最 右边 一 栏 。 你 会 看 到 一 个 像 书 的 
后 面 跟着 Wiki 这 个 单词 ， 如 图 3-1 所 示 。， 
! Or CaflCeI I WOUC | 
© lssues 21 
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| 1 Pull Requests 0 
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图 3-1: 在 侧 边 栏 中 访问 关联 的 维基 


首次 点 击 那 个 链接 后 会 把 你 带 

































































带 到 一 个 页 面 ， 让 你 创建 维基 。GitHub 会 要 求 你 创建 “首页 ”， 











即 Gollum 维基 的 入 口 ( 见 图 3-2)。GitHub 会 自动 创建 一 个 页 面 模板 ， 以 项 目 名称 命 名 ; 

你 可 以 按照 自己 的 需求 修改 模板 。 点 击 “Save Page” 保 在 第 一 个 页 面 ， 创 建 维基 。 

注 1，GitHub 的 界面 改版 了 ， 在 新 版 中 ， 维 基 的 链接 位 于 仓库 名 称 下 面 。 一 一 译 者 注 
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© n This repository Searchoriype a command © Explore Gist Blog Help 国 xd +- XB 


xrd/ TeddyHyde Unwatch- 1 丰 Star 2 人 Fork 0 
Create New Page New Page 

《> 

Home @ 


Write Preview 


ht jhzjhal ia 回 | Blj7j<| 码 


«|u| | 回 | eatmose: CR 1) 3 


Welcome to the TeddyHyde wiki! 











图 3-2: 创建 首页 ， 新建 一 个 维基 


如 果 仓 库 是 公开 的 ， 维 基 也 是 。 公 开 仓 库 的 维基 是 公开 的 ， 任 何人 都 能 访问 。 私 有 仓库 的 
维基 是 私有 的 ， 只 有 有 权限 编辑 仓库 数据 的 用 户 或 组 织 能 访问 。 














下 面 说 明 Gollum 维基 支持 的 标记 。 











3.1.2 标记 和 结构 

Gollum 中 的 文件 可 以 使 用 GitHub 支持 的 任何 标记 格式 编写 ， 包括 ASCIIdoc、Creole、 
Markdown、Org Mode、Pod、RDoc、ReStructuredText、Textile 和 MediaWiki。 支持 的 标 
记 语 言 多 ， 灵 活性 高 ， 却 让 人 难以 选择 。Markdown (及 其 变 体 ) 是 GitHub 中 最 受 欢迎 
的 标记 语言 ， 在 其 他 网 站 (如 Stack Overflow) 中 也 广 受 欢迎 。 如 果 你 不 确定 该 使 用 哪 种 
语言 ， 使 用 Markdown 最 保险 ， 因 为 它 在 GitHub 中 普遍 使 用 。 第 6 章 会 更 为 深入 地 介绍 
Markdown。 














对 于 选择 使 用 Markdown 的 你 来 说 ， 要 知道 除了 Markdown 标准 的 常规 标签 之 外 ，Gollum 
还 添加 了 维基 专用 的 标签 。 这 些 额 外 添加 的 标签 大 都 与 其 他 维基 标记 语言 有 细微 区 别 (有 
的 还 不 兼容 ) ， 所 以 一 定 要 阅读 Gollum 的 文档 (https://github.com/gollum/gollum/wiki)。 下 
下 说 明 其 中 几 个 最 重要 的 标签 。 
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1. 链接 
显然 ， 链 接生 成 的 是 HIML 中 的 <a> 标 签 。 不 同 标记 格式 使 用 的 链接 格式 不 同 ， 
Markdown 使 用 [text](URL) ，Gollum 添加 了 专用 的 链接 标签 : [[Link]]。 


此 外 ， 还 有 如 下 几 点 需要 注意 。 





。 可 以 使 用 竖 线 符号 为 链接 添加 标题 : [[http://foobar.com|A Link to foobar]]。 

。 可 以 添加 外 部 链接 ， 也 可 以 添加 内 部 链接 。 

。 [[Review Images]] 这 样 的 链接 会 转换 成 链接 到 review-images.ext (.ext 是 你 为 维基 选择 
的 文件 扩展 名 ， 极 有 可 能 是 Markdown) 页 面 的 相对 链接 。 


维基 通常 由 大 量 相互 链接 的 页 面 组 成 ， 这 种 链接 结构 有 利于 编写 页 面 。 























前 文 说 过 ，Gollum 维基 与 其 他 维基 使 用 的 标签 虽然 名 法 相似 ， 但 是 仍 有 区 
别 。 例 如 ， 在 MediaWiki 中 ， 带 标题 的 链接 的 结构 是 相反 的 ， 如 [[A link 
to foobar|http://foobar.com]]， 因 此 要 注意 。 














2. 代码 片段 
Gollum 维基 由 GitHub 开发 ， 这 是 一 个 致力 于 改善 软件 开发 者 生活 的 公司 ， 因 此 Gollum 维 
基 显 然 支持 插入 代码 片段 。 插 入 代码 片段 的 方法 是 ， 输 入 三 个 反 引 号 ， 后 面 跟着 可 选 的 语 
言 名 ， 最 后 使 用 三 个 反 引 号 结束 代码 块 。 如 果 指 定语 言 名 ，Gollum 会 正确 高 亮 显示 大 部 分 
语言 的 句法 。 




















ruby 
def hello 

puts "hello" 
end 


以 前 ，Gollum 支持 使 用 下 述 句法 引入 任何 GitHub 仓库 (以 及 任何 分 支 ) 里 的 文件 
(https://github.com/gollum/gollum/wiki/Home/bl6ce34e46e26600dc77bdf9b5aaG6efcaft42026d#gi 
thub-syntax-highlighting) : 





‘* ruby:github:xrd/TeddyHyde/blob/master/Gemfile 


不 过 ， 现 在 已 经 不 支持 了 。 根 据 Gollum 目前 的 文档 ， 这 个 标签 支持 引入 父 级 仓库 里 的 
文件 ; 


“~~ruby:/lib/gollum/app.rb 





可 是 ， 我 发 现 这 样 也 不 行 。 截 至 写作 本 书 时 ， 好 像 还 没有 办 法 把 父 级 仓库 (或 任何 其 他 仓 
库 ) 里 的 代码 插入 维基 的 内 容 里 ， 真 是 悲剧 。 
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3. 结构 组 件 

Gollum 支持 添加 侧 边栏 、 页 头 和 页 脚 。 如 果 仓 库 中 有 名 为 “Sidebar.ext 的 文件 ， 浑 染 后 每 
个 文件 都 会 有 一 个 侧 边栏 。 所 有 文件 和 子 目 录 里 的 所 有 没有 专用 侧 边 栏 的 文件 都 会 自动 添 
加 侧 边栏 。 如 果 想 为 子 目录 添加 专用 的 侧 边栏 ， 在 子 目录 中 添加 一 个 侧 边栏 文件 即 可 ， 这 
个 文件 会 覆盖 顶层 侧 边栏 文件 。 





4. 不 能 使 用 样式 表 和 JavaScript 

为 了 安全 ，Gollum 会 把 原始 标记 文件 中 的 所 有 CSS 和 JavaScript 去 掉 。 在 命令 行 中 运行 
Gollum 时 ( 稍 后 讨论 )， 可 以 使 用 --custom-css 或 --custom-js 开关 引入 自己 的 CSS 或 
JavaScript 文件 ， 不 过 托管 在 GitHub 中 的 Gollum 维基 无 法 引入 这 些 文件 。 


5. 插入 图 像 

在 文档 中 插入 图 像 的 标签 ， 其 格式 与 链接 一 样 ， 例 如 [[ceo.png]]。 这 个 标签 使 用 正确 
的 HTML 标签 把 名 为 ceo.png 的 图 像 插 入 页 面 。 通 常 ， 会 在 这 个 标签 的 基础 上 增加 功能 。 
例如 ， 若 想 添加 边框 和 alt 属性 ， 可 以 使 用 这 样 的 句法 : [[ceo.png|frame|lalt=0ur CEO 
relaxing on the beach]]。 这 个 句法 除了 为 该 图 像 创建 正确 的 HTML 标签 之 外 ， 还 会 添加 
边框 和 alt 文 本 (有 助 于 更 好 地 理解 上 下 文 ， 并 为 视 障 用 户 使 用 的 读 屏 软件 提供 额外 的 信 
息 )。 关 于 图 像 众 多 选项 的 详细 说 明 ， 参 见 Gollum 仓库 的 文档 。 























此 外 ， 我 们 还 可 以 使 用 GitHub 的 编辑 器 添加 图 像 。 不 过 你 会 发 现 ， 使 用 编辑 器 只 能 添加 
图 像 的 地 址 ， 不 能 把 图 像 上 传 到 GitHub 中 ( 见 图 3-3)。 
































Insert Image 


Image URL 








Alt Text 














图 3-3: 不 能 上 传 图 像 ， 只 能 填写 图 像 的 URL 


如 果 非 技术 用 户 想 为 托管 在 GitHub 中 的 Gollum 维基 添加 图 像 ， 几 乎 无 从 下 手 。 接 下 来 ， 
我 们 通过 构建 自己 定制 的 以 图 像 功 能 为 核心 的 Gollum 编辑 器 来 解决 该 问题 ， 而 且 让 它 仍 
能 兼容 常规 的 Gollum 维基 。 非 技术 用 户 使 用 这 个 编辑 器 可 以 上 传 图 像 ， 然 后 按 原 有 的 方 























式 把 维基 发 布 到 GitHub 中 。 


3.2 ”改造 Gollum 


基于 Gollum 开发 一 个 图 像 编 辑 器 有 意义 吗 ? 在 很 多 软件 困 队 中 ， 设 计 团队 和 软件 团队 之 
间 存 在 一 个 矛盾 : 设计 师 通常 不 喜欢 使 用 源码 工具 管理 图 像 。 当 软件 开发 者 所 依赖 的 设 
计 变 化 迅速 时 会 产生 一 个 问题 : 程序 员 很 快 就 跟 不 上 最 新 的 设计 了 。 作 为 一 个 维基 工具 ， 
Gollum 恰好 能 消除 设计 师 与 程序 员 之 间 存 在 的 这 个 矛盾 ， 因 为 对 非 技 术 用 户 而 言 ， 维 基 易 
于 阅读 和 修改 。 由 于 Gollum 是 个 易于 改造 的 维基 ， 我们 可 以 自行 构建 工作 流 工具 ， 让 设 
计 师 便于 管理 图 像 ， 也 让 程序 员 易 于 在 源码 仓库 中 查看 这 些 改 动 。 


现在 仓库 有 两 个 用 途 。 我 们 可 以 把 Gollum 仓库 当 作 标准 维基 ， 还 可 以 借助 我 们 的 应 用 ， 
以 Gollum 默认 界面 所 没有 的 更 强大 的 方式 输入 数据 。 这 样 输入 的 数据 仍 与 Gollum 兼容 ， 
能 托管 在 GitHub 中 。 


首先 ， 安 装 Gollum 这 个 Ruby gem， 然 后 初始 化 仓库 : 






























































$ gem install gollum 

$ mkdir images 

$ cd images 

$ git init . 

$ printf "### Our home" > Home.md 
$ git add Home.md 

$ git commit -m "Initial commit" 





我 们 刚刚 创建 了 一 个 与 Gollum 兼容 的 维基 。 下 面 看 看 这 个 维基 在 Gollum 中 是 什么 样子 。 
执行 goLLunm 命令 ， 然 后 在 浏览 器 中 打开 http://localhost:4567/， 如 图 3-4 所 示 。 





























] localhost:4567/Home 家 
St hn).. Q Hi 
Home ib 2 
Our home 


Last edited by Chris Dawson, 2014-01-17 21:24:41 


Delete this Page 











3-4: 在 笔记 本 电脑 中 查看 维基 的 首页 
可 以 看 出 ， 只 需 这 儿 个 命令 就 能 创建 Gollum 维基 的 基本 结构 。 
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如 果 使 用 命令 行 编辑 Gollum 维基 ， 记 住 ，Gollum 只 在 仓库 数据 中 寻找 文件 。 
如 果 在 工作 目录 中 添加 了 文件 ， 或 者 没 把 文件 提交 到 索引 中 ， 那 么 这 些 文件 
对 Gollum 是 不 可 见 的 。 


























建 协助 我 们 把 图 像 存 储 到 Gollum 维基 中 的 Web 应 用 。 





下 面 开 始 凶 


3.3 ”开始 创建 Gollum 编 辑 器 


下 面 开始 创建 我 们 定制 的 编辑 器 。 我 们 要 使 用 Sinatra， 这 是 一 个 Ruby 库 ， 为 构建 Web 应 
用 提供 了 简单 的 DSL (Domain-Specific Language， 领 域 特定 语言 )。 首 先 ， 创 建 一 个 名 为 
image:rb 的 文件 ， 写 入 如 下 内 容 。 


A 


























require 'sinatra' 
require 'gollum-lib' 
wiki = Gollum: :Wiki.new(".") 
get '/pages' do 
"ALL pages: \n" + wiki.pages.collect { |p| p.path }.join( "\n" ) 
end 


然后 ， 创 建 Gemfile 文件 ， 安 装 依赖 ， 最 后 运行 Web 应 用 。 


$ echo "source 'https://rubygems.org' 

gem "Sinatra ， '1.4.5' 

gem 'gollum-lib', '4.1.0'" >> Gemfile 

$ bundle install 

Fetching gem metadata from https://rubygems.org/.......... 
Resolving dependencies... 

Installing charlock_holmes (0.7.3) 

Using diff-lcs (1.2.5) 

Installing github-markup (1.3.3) 

Using mime-types (1.25.1) 


$ bundle exec ruby image.rb 
$ open http://localhost:4567/pages 


由 于 接口 和 支持 库 列表 都 发 生 了 变化 ， 我 们 指定 使 用 的 goLLum-Lib 至 少 为 4.1.0 版 。 最 后 ， 
执行 bundle exec ruby ;image.rb 命令 ,在 Bundler 中 运行 程序 (即使 用 这 个 Gemfile 文件 
安装 的 gem， 而 不 是 系统 中 的 gem)。 


下 中 会 列 出 Gollum 维基 中 目前 存在 的 文件 。 我 们 只 添加 了 一 个 文件 ， 妈 Home.md。 








页 


* 


3.4 以 编程 的 方式 处 理 图 像 


接 下 来 要 把 图 像 添 加 到 服务 器 中 。 我 们 的 计划 是 : 把 ZIP 文件 上 传 到 系统 中 ， 然 后 解压 ， 
把 文件 添加 到 仓库 中 ， 同 时 也 把 这 些 文件 添加 到 维基 中 。 将 image.rb 脚本 改 成 下 面 这 样 。 
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require 'sinatra' 
require 'gollum-lib’ 
require 'tempfile' 
require 'zip' 
require "rugged ' 


def index( message=nil ) 


response = File.read(File.join('.', 'index.html')) 


response.gsub!( "<!-- message -->\n", 
"<h2>Received and unpacked #{message}</h2>" ) if message 
response 

end 


wiki = Gollum::Wiki.new(".") 


get '/' do 
index() 
end 


post '/unpack' do 


@repo = Rugged::Repository.new('.' 


Qindex = Rugged::Index.new 


zip = params[:zip][:tempfile] 
Zip::Zip.open( zip ) { |zipfilel 
zipfile.each do |f| 


) 


contents = zipfile.read( f.name ) 


filename = f.name.split( File: 


:SEPARATOR ) .pop 


if contents and filename and filename =~ /(png|jp?g|gif)$/i 


puts "Writing out: #{filename} 


end 
end 


} 


index( params[:zip][:filename] ) 
end 


我 们 需要 index.html 文件 ， 下 面 添加 : 


<htmL> 
<body> 
<!-- message --> 


<form method='POST' enctype='multipart/form-data' action='/unpack '> 


Choose a zip file: 

<input type='file' name='zip'/> 
<input type='submit' name='suyubmit'> 
</form> 

</body> 

</html> 


这 个 服务 器 脚本 从 挂 载 点 为 /unpack 的 页 


个 ZP 文 件 。 然 后 ， 这 个 脚本 打开 ZIP 文件 〈 作 为 临时 文件 存储 在 服务 器 端 )， 和 迭代 里 面 





面 接收 POST 请 求 ， 从 传人 脚本 的 参数 中 获取 一 























的 各 个 文件 ， 去 掉 文 件 名 的 完整 路 径 ， 最 后 在 控制 台中 把 文件 名 打印 出 来 (如 果 文 件 看 起 
来 像 是 图 像 )。 不 管 是 否 访 问 服务 器 的 根 目录 ， 也 不 管 是 否 只 向 /unpack 挂 载 点 发 起 POST 
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请 求 ， 首 页 始终 都 要 泻 染 。 解 压 后 泻 染 首页 时 ， 
以 此 表明 脚本 正确 接收 到 了 我 们 发 送 的 文件 。 





要 把 首页 中 的 一 个 注释 禁 换 成 状态 消息 ， 





我 们 要 在 Gemfile 文件 中 添加 两 个 新 Ruby 库 (RubyZip 和 Rugged)。 使 用 下 述 命 令 添 加 所 


需 的 gem， 然 后 重新 运行 那个 Sinatra 服务 器 脚本 





$ echo "gem 'rubyzip', '1.1.7' 

gem 'rugged', '0.23.2'" >> Gemfile 
$ bundle install 

$ bundle exec ruby image.rb 

















o 


Rugged 需要 libgit2 库 (使 用 纯 C 语 言 实现 的 访问 Git 仓库 的 库 )。 使 用 
Rugged 修改 Git 仓库 能 利用 Ruby 语言 的 优雅 ， 还 能 获得 C 语言 的 速度 。 不 
过 ， 因 为 这 个 库 基 于 libgit2， 而 libgit2 需要 C 编译 器 ， 所 以 安装 Rugged 之 
前 要 先 安装 编译 器 。 在 OS X 中 可 以 执行 brew instaLL cmake 命令 安装 ,在 





Linux 中 可 以 执行 apt-get instaLL cmake 命令 安装 。 


然后 ， 打 开 http://localhost:4567/， 上 传 一 个 全 部 是 图 像 的 ZIP 文件， 测试 一 下 。 上 传 ZIP 

















文件 之 后 ， 在 控制 台中 会 看 到 与 下 面 类 似 的 输出 : 





[2014-05-07 10:08:49] INFO WEBrick 1.3.1 





[2014-05-07 10:08:49] INFO ruby 2.0.0 (2013-05-14) 


[x86_64-darwin13.0.0] 


== Sinatra/1.4.5 has taken the stage on 4567 for development with 


backup from WEBrick 


[2014-05-07 10:08:49] INFO WEBrick::HTTPServer#start: pid=46370 


port=4567 

Writing out: IMG1234.png 
Writing out: IMG5678.png 
Writing out: IMG5678.png 


目前 ， 除 了 打印 ZIP 文件 中 图 像 的 名 称 之 外 ， 我 们 什么 也 没 做 。 下 一 闻 ， 我 们 将 真正 地 把 





图 像 存 入 Git 仓库 。 


3.5 使 用 Rugged 库 


这 个 脚本 最 终 的 目标 是 向 Gollum 维基 中 添加 文 伯 
库 里 。Rugged 库 能 轻易 执行 这 种 紧 杂 的 工作 ， 它 


FE， 即 把 文件 添加 到 Gollum 维基 背后 的 仓 
是 最 初 操作 Git 的 Ruby 库 (Grit) 的 继任 


下 








者 。 写 作 本 书 时 ，Gollum 使 用 的 是 Grit 库 ， 这 个 库 也 绑 定 了 libgit2 库 〈 使 用 C 语言 实现 
Git 核心 方法 ， 具 有 便携 性 ) 。Grit 已 经 被 废弃 〈 不 过 仍 有 非 官方 的 维护 者 ) ， 因 此 为 了 长 远 





发 展 ，Gollum 团队 打算 把 支持 Gollum 的 库 换 成 











Rugged。Rugged 使 用 Ruby 编写 ， 与 Git 


仓库 交互 时 ， 比 原始 的 Git 命令 更 优雅 (假如 你 喜欢 Ruby 的 话 )。 你 可 能 猜 到 了 ，Rugged 
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由 GitHub 的 几 名 员工 维护 。 


为 了 让 那个 脚本 能 修改 Git 仓库 ， 我 们 不 能 再 让 它 打 印 文件 名 〈 在 解压 ZIP 文件 的 块 中 使 





用 puts 方法 ) ， 而 要 调用 一 个 新 方法 ， 名 为 write_file_to_repo。 此 外 ， 在 解压 ZIP 文 从 











的 


让 











tt 


代码 块 末尾 要 调用 build_comnmit 方法 ， 为 新 添加 的 文件 构建 提交 。 修 改 后 的 脚本 如 下 所 示 
(没有 列 出 文件 顶部 未 改动 的 代码 ) : 


post '/unpack' do 


@repo = Rugged::Repository.new('.') 
@index = Rugged::Index.new 


zip = params[:zip][:tempfile] 
Zip::Zip.open( zip ) { |zipfilel 
zipfile.each do |f| 
contents = zipfile.read( f.name ) 
filename = f.name.split( File::SEPARATOR ).pop 
if contents and filename and filename =~ /(png|jp?g|gif)$/i 
write_file_ to_repo contents, filename # 写 文 件 


end 
end 
build_commit() # 为 新 添加 的 文件 构建 提交 





} 


index( params[:zip][:filename] ) 


end 


def get_credentials 


contents = File.read File.join( ENV['HOME'], ".gitconfig" ) 
@Qemail = $1 if contents =~ /email = (.+)$/ 
@name = $1 if contents =~ /name = (.+)$/ 


end 


def build_commit 


get_credentials() 

options = {} 

options[:tree] = @index.write tree(@repo) 

options[:author] = { :email => @email, :Name => @name, :time => Time.now } 
options[:committer] = { :email => @Qemail, :name => @Name, :time => Time.now } 
options[:message] ||= "Adding new images" 

options[:parents] = @repo.empty? ? [] : [ @repo.head.target ].compact 
options[:update_ref] = 'HEAD' 


Rugged: :Commit.create(@repo, options) 


end 


def write file to_repo( contents, filename ) 


oid = @repo.write( contents, :blob ) 
Qindex.add(:path => filename, :oid => oid, :mode => 0100644) 


end 





从 上 述 代 码 可 以 看 出 ， 在 Git 仓库 中 创建 提交 的 大 量 繁杂 工作 都 由 Rugged 完成 。Rugged 
提供 的 接口 简单 ， 能 在 Git 仓库 中 创建 blob 文件 (write 方法 )， 能 把 文件 添加 到 暂 存 




















下 
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区 (add 方 法)， 还 能 构建 树 对 象 (write_tree 方法 ) ， 然 后 再 构建 提交 (Rugged: :Commit. 


create ) 。 





为 了 避免 手动 输入 提交 凭据 的 麻烦 ， 我 们 实现 了 get_credentials 方法 ， 从 家 目录 中 
的 .gitconfig 文件 里 读 取 和 凭据。 只 要 设备 中 安装 了 Git， 这 个 文件 可 能 就 存在 ， 如 果 没 有 
这 个 文件 ，get_credentials 方法 会 失效 。 在 我 的 设备 中 ，.gitconfig 文件 的 内 容 如 下 述 代 
码 片段 所 示 。get_credentials 方法 的 作用 很 简单 : 加 载 并 解析 .gitconfig 文件 ， 获 取 用 
户 名 和 电子 邮件 地 址 。 如 果 想 使 用 其 他 方式 获取 凭据 ， 或 者 想 手动 提供 ， 可 以 修改 get_ 
credentials 方法 ， 满 足 自己 的 需求 。butLd_commit() 方法 会 使 用 实例 变量 genatL 和 1 


name。 









































[user] 

name = Chris Dawson 

email = xrdawsonGgmaiL.com 
[credentiall] 

helper = cache --timeout=3600 

















村 


而 验证 上 传 ZIP 文件 后 是 否 能 正确 处 理 。 上 传 文件 后 ， 打 开 终 端 窗口 ， 执 行 下 述 命令 : 




















$ git status 
让 人 奇怪 的 是 ， 我 们 会 看 到 如 下 输出 情况 : 


$ git status 
On branch master 
Changes to be committed: 
(use "git reset HEAD <file>..." to unstage) 


deleted: images/3190a7759f7f668.../IMG_20120825_164703.jpg 


deleted: images/3190a7759f7f668.../IMG 20130704_151522.jpg 
deleted: images/3190a7759f7f668.../IMG 20130704_174217.jpg 


我 们 是 添加 文件 啊 ， 为 什么 Git 报告 说 文件 被 删除 了 呢 ? 








为 了 和 弄 明白 怎么 回 事 ， 要 知道 在 Git 中 文件 有 三 个 存储 区 : 工作 目录 、 暂 存 区 和 仓库 。 工 
作 目 录 中 存储 的 是 正在 处 理 的 本 地 文件 。 根 据 文档 ，git status 命令 的 作用 是 “显示 工作 
区 的 状态 ”。Rugged 操作 的 是 仓库 本 身 ， 上 述 代 码 中 的 Rugged 方法 调用 操作 的 是 暂 存 区 ， 
然后 构建 提交 。 这 一 点 要 特别 注意 ， 因 为 如 果 只 使 用 Rugged 方法 调用 执行 写 操作 ， 文 件 
不 会 存 入 工作 目录 ， 此 时 ， 在 本 地 运行 的 Gollum 中 ， 维 基 页 面 里 无 法 引用 那些 文件 。 下 


一 方 会 修正 这 个 问题 。 


















































现在 ,我 们 把 文件 添加 到 仓库 中 了 ， 可 是 还 没有 把 文件 提供 给 维基 。 下 面 ， 我 们 要 修改 这 
个 服务 器 脚本 ,把 各 个 文件 写 入 一 个 维基 页 面 中 ， 以 供 查 看 。 如 前 所 述 ， 文 件 既 要 写 入 工 
作 区 ， 也 要 写 入 仓库 (使 用 Rugged 库 中 的 write 方法 )。 然 后 ， 我 们 可 以 生成 一 个 Review 
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文件 ， 列 出 上 传 的 所 有 


3.6 ”优化 图 像 存储 


如 果 设 计 师 上 传 相 同 的 图 像 两 次 会 怎样 ? 我 们 


图 像 。 








及 





























的 代码 根据 父 级 仓库 的 SHA 散 列 值 把 上 传 














的 图 像 写 入 硬盘 中 的 某 个 路 径 (因此 ， 即 使 与 之 前 上 传 的 文件 相同 ， 也 会 写 入 不 同 的 路 
径 )。 对 外 行人 来 说 ， 这 看 似 是 多 次 添加 相同 的 文件 。 然 而 ， 根 据 Git 的 特性 ， 相 同 的 文件 


可 以 多 次 添加 ， 而 且 首 次 添加 之 后 ， 再 添加 相同 的 文件 不 会 消耗 额外 的 存储 空间 ( 








Eg 
只 会 稍 

















微 增加 树 结构 的 大 小 )。 向 Git 仓库 添加 文件 时 ，Git 会 根据 文件 的 内 容 生成 SHA 散 列 值 。 





例如 ， 空 文件 对 应 的 SHA 散 列 值 始终 相同 : ? 











$ echo -en "blob 0\0" | shasum 

e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 
$ printf '' | git hash-object -w --stdin 
e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 


如 果 后 面 上 传 的 ZIP 文件 中 只 有 一 两 个 文件 与 





次 引用 相同 的 文件 。 可 惜 ，GitHub 没 像 常规 的 仓库 那样 为 维基 提供 查看 统计 资料 的 界 下 


不 过 ， 在 本 地 仓库 中 可 以 执行 Git 子 命令 coun 


含 两 个 图 像 的 ZIP 文件 之 后 ， 我 执行 了 count-objects 命令 ， 看 到 如 下 输 晶 


$ git gc 


$ git count-objects -v 
count: 0 

size: 0 

in-pack: 11 

packs: 1 

size-pack: 2029 
prune-packable: 0 
garbage: 0 
size-garbage: 0 


审查 第 一 个 ZIP 文件 ， 看 到 如 下 统计 资料 : 


$ unzip -L ~/Downloads/Photos\ \(4\).zip 

Archive: 
Length 
1189130 01-01-12 00:00 
889061 01-01-12 00:00 


2078191 


Date Time Name 


2 files 


下 面 我 们 再 审查 一 个 ZIP 文件 ， 甚 中 有 两 个 文 们 


IMG_20130704_ 
IMG_20130704_ 


之 前 上 传 的 ZIP 文件 不 同 ，Git 能 正确 地 多 

















o 


t-objects 查看 仓库 的 大 小 。 例 如 ， 上 传 包 


由 . 
口 : 





/Users/xrdawson/Downloads/Photos (4) .zip 


151522.jpg 
174217. jpg 





F 与 之 前 相同 ， 此 外 又 添加 了 一 个 








注 











像 文 件 : 





E 2: 这 篇 博文 对 此 做 了 极 好 的 说 明 : http://alblue.bandlem.com/2011/08/git-tip-of-week-objects.html。 
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unzip -L ~/Downloads/Photos\ \(5\).zip 

Archive: /Users/xrdawson/Downloads/Photos (5).zip 
Length Date Time Name 
1189130 01-01-12 00:00 IMG_20130704_151522.jpg 
566713 01-01-12 00:00 IMG_20120825_164703.jpg 
889061 01-01-12 00:00 IMG_20130704_174217.jpg 


2644904 3 files 








然后 ， 上 传 第 二 个 ZIP 文件 。 再 次 执行 count-objects 命令 (在 git gc 命令 之 后 执行 ， 这 
个 命令 用 于 高 效 打包 文件 ， 让 输出 更 易于 阅读 ) ， 看 到 如 下 输出 : 


$ git gc 


$ git count-objects -v 
count: 0 

size: 0 

in-pack: 17 

packs: 1 

size-pack: 2578 
prune-packable: 0 
garbage: 0 
size-garbage: 0 





注意 ， 包 大 小 只 增加 了 约 0.5MB， 即 那 第 三 个 文件 压缩 后 的 大 小 。 而 更 应 该 注意 的 是 ， 虽 
然 另外 两 个 文件 从 不 同 的 路 径 添 加 ， 但 是 对 仓库 的 大 小 设 有 影响 。 


如 果 再 次 上 传 第 二 个 ZIP 文件 ， 我 们 要 重新 生成 并 提交 Review.md 文件 的 一 个 新 版 本 ， 但 
是 无 需 读 取 图 像 目录 ， 然 后 在 Git 仓库 中 新 建文 件 (尽管 文件 的 路 径 变 了 )， 因 此 对 仓库 的 
影响 微乎其微 : 


























$ git gc 


$ git count-objects -v 
count: 0 

size: 0 

in-pack: 21 

packs: 1 

size-pack: 2578 
prune-packable: 0 
garbage: 0 
size-garbage: 0 


可 以 看 出 ， 包 大 小 几乎 没 变 ， 这 表明 只 新 增 了 一 个 Git 树 对 象 和 一 个 提交 对 象 。 在 仓库 
中 ， 这 些 文件 放 在 不 同 的 路 径 ， 因 此 不 管 访问 的 是 哪个 版 本 ， 查 看 页 面 都 能 正确 将 其 显示 
出 来 。 








$ find images 
images 





images/7507409915d00ad33d03c78af0a4004797eec4b4 

images/7507409915d00ad33d03c78af0a4004797eec4b4/IMG_20120825_164703. jpg 
images/7507409915d00ad33d03c78af0a4004797eec4b4/IMG_20130704_151522.jpg 
images/7507409915d00ad33d03c78af0a4004797eec4b4/IMG_20130704_174217. jpg 
images/7f9505a4bafe8c8f654e22ea3fd4dab8b4075f75 

images/7f9505a4bafe8c8f654e22ea3fd4dab8b4075f75/IMG_20120825_164703. jpg 
images/7f9505a4bafe8c8f654e22ea3fd4dab8b4075f75/IMG_20130704_151522.jpg 
images/7f9505a4bafe8c8f654e22ea3fd4dab8b4075f75/IMG_20130704_174217. jpg 
images/b4be28e5b24bfa46c4942d756a3a07efd24bc234 

images/b4be28e5b24bfa46c4942d756a3a07efd24bc234/IMG_20130704_151522.jpg 
images/b4be28e5b24bfa46c4942d756a3a07efd24bc234/IMG_20130704_174217. jpg 


Git 和 Gollum 无 需 重 载 仓库 就 能 把 相同 的 文件 存储 在 不 同 的 路 径 上 。 


3.7 在 GitHub 中 查看 


维基 的 作用 是 注解 开发 项 目 。 如 果 你 按照 前 文 所 说 的 做 了 ， 而 且 为 仓库 新 建 了 维基 ， 那 么 
你 可 以 使 用 image.rb 脚本 推送 所 做 的 改动 。 新 建 维基 之 后 ， 在 页 面 右边 寻找 “Clone this 
wiki locally” 文 本 框 ， 如 图 3-5 所 示 。 



































wv Pages (1) 


Home 


Add a custom sidebar 


Clone this wiki locally 


git@github.com:xrd/webipha | Es 


图 Clone in Desktop 











3-5: 找到 维基 的 克隆 URL 
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复制 那个 链接 ， 然 后 打开 终端 窗口 。 我 们 将 在 终端 里 为 本 地 仓库 添加 远程 URL， 这 样 便 可 
以 同步 仓库 ， 把 图 像 发 布 到 GitHub 中 。Gollum 维基 的 URL 结构 简单 ， 只 是 在 仓库 的 克 
隆 URL 后 面 加 上 .wiki (不 过 是 在 末尾 的 .git 扩展 名 之 前 )。 因 此 ， 如 果 仓 库 的 克隆 URL 
是 git@github.com:xrd/webiphany.com.git， 那 么 相应 的 维基 的 克隆 URL 便 是 git@github. 
com:xrd/webiphany.com.wiki.git。 知 道 URL 之 后 ， 可 以 使 用 下 述 命令 为 本 地 仓库 添加 远 
程 仓库 地 址 : 











$ git remote add origin git@github.com:xrd/webiphany.com.wiki .git 
$ git pull # 这 个 命令 会 要 求 你 合并 改动 …… 
$ git push 





拉 取 仓库 后 ，Git 会 要 求 你 合并 改动 ， 因 为 本 地 仓库 中 没有 GitHub 创建 的 Home.md 文件 。 
此 时 ， 直 接合 并 即 可 。 后 面 的 git push 命令 用 于 发 布 改动 。 现 在 访问 维基 ， 会 发 现 右边 的 
Pages 侧 边 栏 中 多 了 一 个 文件 。 点 击 Review， 在 页 面 中 可 以 看 到 我 们 最 近 添 加 的 图 像 ， 如 
3-6 所 示 。 
































和 外 GitHub, Inc. [US] https://github.com/xrd/android-project1/wiki/Review [eo) [| a < SS 
© 四 Thls repository v Search ortype a command © Explore Gist Blog Help [所 | xrd 二 ”加 
E | xrd / android-project1 GUnwatch- 1 | 让 Star 0 | 全 For 
Review Eait 
3 commits 


Review Images Pages (2 


Home 


Review 


©~IMG_20130704_151522.jpg 


Add a custom sidebar 


Clone this wiki locally 


gite@github.com:xrd/android | 篇 


较 Clone in Desktop 














3-6: 查看 图 像 的 页 面 
我 不 确定 设计 师 提供 一 张 沙发 图 的 原因 ， 不 过 他 肯定 有 他 自己 的 理由 。 








发 布 文件 之 后 ， 我 们 可 以 点 击 侧 边栏 中 的 Review 链接 ， 查 看 Review 页 面 的 最 新 版 。 此 
外 ， 还 可 以 点 击 页 面 标题 正 下 方 的 “3 Commits”( 甚 中 的 数字 会 根据 文件 的 提交 次 数 变 
动 )， 查 看 这 个 文件 的 修订 版 本 。 在 打开 的 页 面 中 有 文件 的 完整 历史 ， 如 图 3-7 所 示 。 








入 后 
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龟 GitHub, Inc. [US] https://github.com/xrd/android-project1/wiki/Review/_history 


XGO 





This repository ~ 


O 


Compare Revisions 





Search ortype a command 


xrd /android-project1 


History: Review 


© “ Explore Gist Blog Help 


SUnwatchv 1 


圆 xd +- xX 


址 Star 0 沙 For 


Edit Page 











口 国 xrd Adding new images 

日 国 xrd Adding new images 

口 国 xrd Adding new images 
图 3-7: 通过 提交 日 志 查 看 维基 的 历史 


点 击 SHA 散 列 值 可 以 查看 页 本 

















版 本 之 间 切 换 需 要 点 击 两 次 ， 一 次 从 Review 页 面 到 修订 版 本 列表 ， 


的 修订 版 本 。 不 过 这 么 做 可 以 查看 设计 师 提供 的 医 


种 便捷 的 方式 ， 可 以 从 一 个 
不 过 我 们 可 以 自己 动手 ， 在 Review 页 再 











如 果 GitHub 提供 一 








好 了 ， 可 惜 现在 还 未 提供 。 
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像素 材 变 化 情况 
修订 和 版 本 转 到 父 级 





i 相应 的 修订 版 本 ， 以 及 文档 在 彼 时 的 状态 


。 可 惜 ， 在 修订 
另 一 次 是 进入 想 查看 





(之 前 的 ) 修订 版 本 就 




















接 ， 通 过 特定 的 方式 ， 


3.8 
在 我 们 的 示例 中 ， 现 在 上 








让 它 指向 页 





看 的 前 一 版 。 











改善 修订 版 本 导航 


只 有 三 个 修订 版 本 ， 而 且 都 使 用 相同 的 提交 


i 中 添加 一 个 特殊 的 链 


说 明 (“Adding new 


images )。 这 种 说 明 不 够 清晰 ， 也 不 便于 区 分 不 同 的 修订 版 本 ， 但 是 其 对 于 理解 图 像素 材 


的 变化 情 ? 


网 是 很 重要 的 。 我 们 可 以 轻松 地 改善 这 种 不 便 。 


首先 ， 在 上 传 表单 中 添加 一 个 字段 ， 用 于 输入 提交 说 明 : 


<htmL> 
<body> 
<!-- Message --> 





<form method="'POST' enctype='multipart/form-data' action='/unpack '> 


Choose a zip file: 
<input type=" 
<input type= 
<input type= 
</form> 
</body> 
</htmL> 


"Submit 


然后 ， 通 过 修改 一 行 
本 里 的 提交 说 明 : 


选项 散 列 ， 


file' name='zip'/> 
'text' name='message' placeholder='Enter commit message'/> 


name='submit'> 


即 把 提交 说 明 设 为 通 


过 参数 传 入 的 值 ， 来 修改 image.rb 脚 
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options[:committer] = { :email => QemaiL，:name => @name, :time => Time.now } 
options[:message] = params[ :message] 
options[:parents] = @repo.empty? ? [] : [ @repo.head.target ].compact 


现在 ,设计 师 发 布 新 的 UI 素材 时 可 以 指明 改动 了 什么 ， 而 改动 会 记录 在 案 ， 能 通过 
GitHub 的 修订 历史 页 面 查看 。 


3.9 ”修缮 素材 页 面 之 间 的 链接 
如 前 所 述 ， 进 入 Review 页 面 的 其 个 修订 版 本 之 后 ， 无 法 快速 在 版 本 之 间 切 换 。 不 过 ， 你 
应 该 还 记得 我 们 前 面 使 用 父 级 SHA 散 列 值 构 建 过 图 像 的 链接 。 同 理 ， 在 某 个 修订 版 本 页 
看 查看 历史 时 ， 可 以 在 图 像素 材 页 面 插入 一 个 导航 链接 。 





















































/说 














这 一 次 要 改 的 也 不 多 ， 只 需 修 改 write_review file 方法 中 的 一 行 代码 。 在 创建 指向 各 个 
像 文 件 链接 的 那个 代码 块 之 后 增加 一 行 ， 通 过 erepo.head.target 获得 Rugged 对 象 中 的 父 
级 SHA 散 列 值 ， 然 后 构建 指向 父 级 文档 的 链接 。 这 个 链接 用 于 访问 历史 中 的 前 一 个 修订 
版 本 : 





files.each do |f| 
contents += "### #{f} \n[[#{dir}/#{f}]]\n\n" 
end 
contents += "[Prior revision (only when viewing history)]" + 
"(#{@repo.head.target})\n\n" 


File.write review filename, contents 
oid = @repo.write( contents, :blob ) 


现在 ， 查 看 Review 文件 的 历史 时 ， 会 看 到 指向 之 前 版 本 的 链接 。 那 么 ， 能 不 能 添加 指向 
历史 中 下 一 个 版 本 的 链接 呢 ? 可 惜 ， 我 们 不 能 预料 到 仓库 中 下 一 个 提交 的 SHA 散 列 值 
因此 这 个 Ruby 脚本 无 法 在 Review.md 文件 中 构建 这 样 的 链接 。 不 过 ， 我 们 可 以 变通 一 
下 ， 使 用 浏览 器 的 后 退 按钮 回 到 浏览 历史 中 的 前 一 个 页 面 。 你 可 能 想 更 进一步 ， 在 链接 中 
使 用 JavaScript， 调 用 window.history.back()， 但 是 Gollum 会 从 泻 染 后 的 标记 文件 中 去 掉 
JavaScript， 因 此 这 样 行 不 通 。 一 般 来 说 ， 这 是 正确 的 处 理 方式 ， 因 为 我 们 不 希望 维基 页 面 
中 出 现 恶意 标记 ， 可 是 对 这 个 问题 而 言 ， 却 限制 了 选择 。 


可 惜 ， 直 接 查 看 Review 文件 时 ， 这 种 链接 无 效 (如 果 点 击 ， 会 把 你 带 到 一 个 页 面 ， 让 你 
新 建 页 面 )。Gollum 与 Jekyll 不 同 ， 它 不 支持 Liquid 标签 ， 如 果 支 持 的 话 ， 可 以 使 用 用 户 
名 和 仓库 名 构建 链接 。 目 前 ， 我 们 无 法 访问 这 些 变量 ， 因 此 要 使 用 相对 链接 ， 所 以 链接 只 
在 查看 Review 页 面 的 历史 时 有 效 ， 而 直接 访问 Review 页 面 时 无 效 。 这 个 局 限 不 影响 查看 
文件 ， 不 过 还 是 要 让 相关 人 员 知 道 。 
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3.10 ”小 结 


本 章 ， 我 们 学 习 了 如 何 从 头 开始 创建 Gollum 维基 ， 包 括 在 GitHub 中 创建 ， 以 及 使 用 命令 
行 创建 新 仓库 的 方式 。 然 后 ， 我 们 介绍 了 Gollum 命令 行 工具 的 多 种 用 法 ， 了 解 到 自己 运 
行 Gollum 服务 器 时 使 用 命令 行 工 具 的 好 处 。 最 后 ， 我 们 围绕 图 像 功能 ， 使 用 Rugged 和 
Sinatra 两 个 Ruby 库 定制 了 一 个 Gollum 图 像 编 辑 器 。 




















下 一 章 换个 完全 不 同 的 话题 : 构建 一 个 搜索 GitHub 工 单 的 GUI 应 用 。 我 们 将 使 用 Python 
构建 该 应 用 。 
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第 4 章 


Python 和 Search AP1 








数据 多 到 一 定 程度 后 ， 再 大 的 组 织 也 不 可 能 做 到 让 一 切 轻 松 可 查 。Google 告诉 我 们 ， 当 
数据 达到 一 定 规模 后 ， 唯 一 有 效 的 系统 是 : 搜索 框 。 在 GitHub 中 有 两 种 仓库 : 一 种 是 你 
能 直接 访问 的 (数量 较 少 )， 这 是 一 种 单 层 结构 ， 在 脑 中 就 能 直接 记 住 ， 另 一 种 是 数 百 万 
个 数 也 数 不 完 的 其 他 人 创建 的 公开 仓库 ， 你 可 以 通过 搜索 框 提供 的 强大 功能 找到 所 需 的 
内 容 。 


令 人 欣喜 的 是 ，GitHub 还 通过 API 开放 了 搜索 功能 ， 以 便 在 你 自己 的 应 用 中 使 用 。 通 过 
GitHub 的 Search API， 我 们 能 使 用 所 有 的 内 建 搜索 功能 ， 包 括 逻 辑 和 作用 域 运 算 符 ， 如 
"or" 和 "user"。 你 可 以 在 自己 的 应 用 中 集成 这 个 功能 ， 为 用 户 提供 十 分 强大 的 搜索 功能 ， 
让 他 们 找到 自己 所 需 的 内 容 。 
































本 章 将 深入 了 解 这 个 API， 并 尝试 使 用 它 构 建 一 个 有 用 的 应 用 。 我 们 将 说 明 Search API 的 
结构 ， 返 回 的 结果 有 哪些 类 型 ， 以 及 如 何 利用 它 改 善 我 们 团队 中 某 个 人 的 工作 。 


4.1 Search API 概 述 


Search API 由 四 部 分 组 成 : 仓库 、 代 码 、 工 单 和 用 户 。 这 些 API 的 作用 不 同 ， 结 果 的 格式 
也 不 同 ， 不 过 主要 行为 基本 一 致 。 我 们 先 讨 论 相 同 点 ， 这 样 便于 理解 后 文 对 各 个 API 返回 
结果 的 说 明 。 这 些 API 主要 有 四 个 共同 特征 。 


4.1.1 身份 验证 


用 户 的 身份 对 搜索 词 条 得 到 的 结果 有 影响 ， 因 此 一 定 要 知道 身份 验证 方面 的 知识 。 我 们 在 








46 


1.6 节 详 述 了 GitHub 验证 身份 的 方式 。 不 登录 也 能 使 用 Search API， 不 过 有 几 个 限制 。 


首先 ， 只 能 搜索 公开 仓库 。 如 果 只 与 开源 软件 打交道 ， 这 或 许 不 算是 限制 ， 可 是 ， 你 的 应 
用 的 用 户 可 能 想 访问 他 们 自己 的 以 及 任何 所 属 组 织 的 私有 代码 。 此 外 ， 所 有 企业 版 仓库 都 
是 私有 的 ， 匿 名 搜索 没有 任何 作用 。 


其 次 ， 验 证 身份 后 频率 限制 得 到 提升 。 搜 索 的 频率 限制 比 其 他 API 严格 ， 因 为 搜索 要 消 
耗 很 多 计算 资源 ， 因 此 对 匿名 搜索 的 限制 更 严 。 写 作 本 书 时 ， 根 据 文 档 ， 对 匿名 搜索 的 
限制 是 每 分 钟 5 次 ， 而 验证 身份 后 ， 每 分 钟 可 查询 20 次 。 对 频率 限制 的 详细 说 明 参 见 
]:7:67 匠 :。 






































下 面 以 表格 的 形式 列 出 : 


























芽 名 验 证 后 
结果 中 包含 私有 仓库 否 是 
可 以 在 企业 版 中 使 用 香 是 
频率 限制 每 分 钟 5 次 每 分 钟 20 次 


4.1.2 ”结果 的 格式 
不 管 搜 索 什么 ，Search API 返回 的 结果 都 是 特定 的 格式 。 下 面 是 某 次 查询 的 结果 示例 ,我 
对 其 做 了 大 量 节 略 ， 以 便 让 你 看 清 始终 存在 的 部 分 。 



































{ 
"total_count": 824, 
"incomplete_results": false, 
"items": [ 


er 3.357718 
} 
] 
} 
从 上 往 下 看 ，total_count 字段 表示 此 次 查询 得 到 的 搜索 结果 总 数 。 搜 索 结 果 通 常 有 几 千 
个 ， 毕 竞 GitHub 中 有 几 百 万 个 仓库 。 默 认 只 返回 前 30 个 搜索 结果 ， 不 过 可 以 在 URL 中 
使 用 page 和 per_page 两 个 查询 参数 定制 。 例 如 ， 问 下 述 URL 发 起 GET 请 求 会 得 到 45 个 
结果 ， 而 且 从 第 46 个 算 起 : 

















search/repositories?q=foobar&page=2&per_page=45 





通常 ， 每 页 限制 返回 100 个 结果 。 





incomplete_results 字段 表示 GitHub 对 Search API 所 做 的 计算 限制 。 如 果 搜 索 耗 时 太 长 ， 
那么 GitHub API 会 在 执行 中 途 停止 ， 返 回 已 经 得 到 的 结果 ， 并 把 这 个 标志 设 为 true。 大 
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多 数 情况 下 ， 这 不 会 导致 问题 ，total_count 字段 的 值 是 搜索 结果 的 总 数 ， 然 而 ， 如 果 是 
复杂 的 词 条 ， 可 能 只 会 得 到 部 分 结果 。 























搜索 结果 是 一 个 数组 ， 存 在 items 字段 中 ， 而 且 各 个 元 素 都 有 score 字段 。 这 个 字段 的 值 
是 数字 ， 不 过 只 是 结果 与 词 条 匹配 程度 的 相对 值 ， 用 于 默认 排序 ， 分 值 高 的 在 前 面 。 如 果 
对 这 个 字段 感 兴趣 ， 要 记 住 ， 仅 当 与 同一 个 词 条 的 其 他 结果 比较 时 ， 它 才 有 意义 。 得 到 50 
分 的 结果 不 一 定 比 得 到 5 分 的 结果 “好 ”十 倍 。 


























下 表 总 结 了 重要 字段 的 意义 。 














字 段 总 上 尺 

total_count 搜索 结果 总 数 

incomplete_results 如 果 搜 索 在 结束 前 中 止 ， 值 为 true 
items 搜索 结果 列表 

(item).score 单个 搜索 结果 的 相关 度 





4.1.3 搜索 运算 符 和 限定 符 
当然 ， 最 好 能 避免 分 页 ， 或 者 至 少 在 第 一 页 返回 最 好 的 结果 。 限 定 符 和 运算 符 有 助 于 删 减 
搜索 结果 ， 减 少 分 页 数量 ， 有 时 还 能 把 正确 的 结果 移 到 顶部 。 


对 Search API 来 说 ， 所 有 搜索 都 要 有 搜索 词 条 ， 而 这 个 词 条 要 经 过 编码 ， 通 过 URL 中 
的 q 参数 传 入 。 大 多 数 词 条 是 自由 词 ， 不 过 这 个 API 还 支持 一 些 更 强大 的 句法 ， 例 如 下 
述 形式 。 


























。 x AND y， 还 可 以 使 用 OR 或 NOT 

。 user:<name>， 其 中 name 是 用 户 或 组 织 的 名 称 

。 repo:<name> 

。 language:<name> 

。 created:<date(s)> 

。 extension:<pattern>， 匹 配 文件 扩展 名 (如 py 或 ini) 


数 








PS 人 





直 和 日 期 可 以 指定 范围 





i 




















。 2015-02-01 只 匹配 指定 的 日 期 
。 <2015-02-01 匹配 指定 日 期 之 前 的 任何 日 期 
。 2015-02-01..2015-03-01 匹配 指定 范围 内 的 日 期 ， 包 括 两 端点 





例如 ， 如 果 想 查找 用 户 tpope 在 2012 年 7 月 编写 的 代码 ， 查 询 参 数 可 以 写 为 "user:tpope 
created:2012-07-01..2015-07-31"。 编 码 后 的 URL 如 下 : 





search/repositories?q=user%3Atpope+created%3A2012-07-01. .2015-07-31 





如 果 只 想 搜 索 Python 代码 ， 那 么 可 以 添加 代码 Language=python， 在 URL 后 面 加 上 编码 
+language%3Apython。 














此 外 还 有 其 他 选项 。https://github.com/search/advanced 页 面 提供 了 一 个 UI[， 能 帮助 你 构建 
一 条 查询 。 





4.1.4 排序 


使 用 搜索 词 条 运算 符 删 减 后， 得 到 的 结果 如 果 还 不 是 最 重要 的 元 素 ， 或 许可 以 再 做 排序 。 
搜索 结果 使 用 特定 的 顺序 返回 ， 而 不 是 随机 的 。 默 认 按 “最 佳 匹 配 ” 排 序 ， 即 按照 搜索 得 
分 排序 结果 ， 得 分 高 的 在 前 面 。 如 果 想 改变 排序 依据 ， 可 以 把 sort 查询 参数 设 为 stars、 
forks 或 updated， 例 如 search/repositories?q=foobar&sort=stars。 



























































此 外 ， 还 可 以 使 用 order 参数 逆向 排序 ， 例 如 search/repositories?q=foobar&sort=stars& 
order=desc。 默 认 的 排序 方式 是 desc (降序 ) ， 不 过 也 可 以 设 为 asc 来 逆向 排序 。 


4.2 Search API 详解 


至 此 ， 我 们 已 经 概述 了 这 些 API 的 相同 点 ， 下 面 详 述 细节 。Search API 分 为 四 类 : 仓库 、 
代码 、 工 单 和 用 户 。 这 四 类 的 基本 机 制 是 一 样 的 : 向 端点 发 起 GET 请 求 ， 通 过 q 参数 传 
入 经 过 URL 编码 后 的 搜索 词 条 。 下 面 分 述 各 个 API 删 减 后 的 响应 ， 同 时 说 明 部 分 值得 关 
注 的 字段 。 


4.2.1 搜索 仓库 


search/repositories 端点 通过 仓库 的 元 数据 查找 匹配 词 条 的 仓库 。 默 认 使 用 的 元 数据 是 项 
目的 名 称 和 描述 ， 不 过 还 可 以 在 词 条 中 指定 in:readme， 搜 索 自述 文件 。 其 他 限定 符 参阅 
文档 : https://developer.github.com/v3/search/#search-repositories。 


















































search/repositories?q=foobar 查询 可 能 会 得 到 如 下 响应 : 


{ 
"total_count": 824, 
"incomplete_results": false, 
"items": [ 
{ 
"id": 10869370 ， 
"name": "foobar " ， 
"fuLL_name" : "iwhitcomb/foobar", 
"owner" : { 
"login": "iwhitcomb", 
"id": 887528, 
"avatar_url": "https://avatars.githubusercontent.com/u/887528?Vv=3", 
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"private": false, 

"html_url": "https://github.com/iwhitcomb/foobar", 
"description": "Drupal 8 Module Example", 

"fork": false, 


"score": 59.32314 
和 


] 
} 


items 中 的 各 个 元 素 是 仓库 的 描述 信息 ， 包 罗 万 象 ， 例 如 仓库 界面 的 URL (html_url)、 属 
主 的 头像 (owner.avatar_url)， 以 及 适合 使 用 Git 克隆 仓库 的 URL (git_ur1)。 


4.2.2 ”搜索 代码 


search/code 端点 用 于 搜索 仓库 里 的 内 容 。 我 们 可 以 在 文件 的 内 容 中 查找 匹配 内 容 ， 也 可 
以 在 文件 的 路 径 中 查找 〈 使 用 in:path)。( 其 他 限定 符 参阅 文档 : https://developer.github. 
comy/v3/search/#search-code。) 









































这 个 API 有 几 个 限制 是 其 他 搜索 端点 没有 的 ， 因 为 服务 器 要 排查 大 量 数据 寻找 匹配 内 容 。 
第 一 ， 要 提供 一 般 性 的 搜索 词 条 (要 匹配 的 短语 ) ， 其 他 几 个 API 在 词 条 中 可 以 只 指定 
运算 符 (如 Language:python), 但 是 这 个 API 不 可 以 。 第 二 ， 词 条 中 所 有 的 通配符 都 会 
被 忽略 。 第 三 ， 不 会 搜索 超过 一 定 大 小 的 文件 。 第 四 ， 只 搜索 项 目的 默认 分 支 ， 通常 为 
master。 第 五 ， 这 可 能 是 最 重要 的 一 点 ， 必 须 使 用 user:<name> 限定 符 指定 仓库 的 属 主 ， 
不 能 一 次 搜索 全 部 仓库 。 

















返回 的 JSON 如 下 所 示 : 


上 
"total_count": 9246， 
"incomplete_results": faLse， 
"items": [ 
江 
"name": "migrated 0000.js", 
"path": "test/fixtures/ES6/class/migrated 0000.js", 
"sha": "37bdd2221a71b58576da9d3c2dcoef0998263652" ， 
"urtL' : 人 
"git_url": "…", 
"html_url": ”…”， 
"repository": { 
"id": 2833537 ， 
"name": "esprima", 
"full_name": "jquery/esprima", 
"owner": { 
"login": "jquery", 
"id": 70142 ， 





"avatar_url": "https://avatars.githubusercontent.Ccom/u/70142?v=3"， 


}， 


"private": faLse， 
}， 
"score": 2.3529532 


}， 


] 
} 


各 个 元 素 中 有 关于 匹配 文件 的 数据 ， 例 如 文件 名 和 文件 的 几 种 URL。 后 面 还 有 文件 所 属 仓 
库 的 数据 。 最 后 是 得 分 ， 用 于 默认 的 “最 佳 匹 配 ” 排 序 。 


4.2.3 搜索 工 单 


仓库 中 不 仅 有 代码 。search/issues 端点 在 项 目 中 搜索 匹配 词 条 的 的 工 单 和 拉 取 请 求 。 这 
个 端点 可 以 使 用 的 搜索 限定 符 众 多 ， 举 例如 下 。 


























。 type 


直 为 表示 拉 取 请 求 的 “pr ， 或 者 表示 工 单 的 “issue” (默认 兼 具 二 者 ) 。 





。 team 


匹配 讨论 中 提 到 指定 团队 的 工 单 〈 仅 用 于 在 你 所 属 的 组 织 中 搜索 ) 。 








e no 


匹配 没有 某 个 数据 的 工 单 (如 “no:label )。 





此 外 还 有 很 多 ， 详 情 参 阅 文档 : https://developer.github.com/v3/search/#search-issues。 





请 求 这 个 端点 得 到 的 响应 如 下 : 


{ 
"total_count": 1278397, 
"incomplete_results": false, 
"items": [ 


wurl": ".", 
"Labels_url": "……", 
"comments_url": ".…", 
"events_url": ".…", 
"html_url": "", 
"id": 69671218, 
"number": 1， 


"title": "Classes", 
"user": { 
"login": "reubeningber", 


"id": 2552792, 
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"avatar_url": … ， 


}， 


"LabetLs" : [ 
"state": "open", 


"locked": false, 

"assignee": null, 

"milestone": null, 

"comments": 0， 

"created_at": "2015-04-20T20:18:562Z"， 

"updated_at": "2015-04-20T20:18:562Z"， 

"closed_at": null, 

"body": "There should be an option to add classes to the UL and li...", 
"score": 22.575937 


}， 

















同样 ， 列 表 中 的 各 个 元 素 是 查询 这 个 API 得 到 的 结果 。 这 里 有 很 多 有 用 的 数据 ， 例 如 工 单 
的 标题 (title)、 标 注 (labels)， 以 及 指向 拉 取 请 求 相关 数据 的 链接 (pull_request.url， 
如 有 果 结 果 不 是 拉 取 请 求 ， 没 有 这 个 字段 )。 


4.2.4 搜索 用 户 

前 面 几 个 Search API 都 与 仓库 有 关 ， 但 是 这 个 端点 搜索 的 是 一 个 不 同 的 命名 空间 一 一 
GitHub 用 户 。 默 认 情 况 下 只 搜索 用 户 的 登录 名 和 公开 的 电子 邮件 地 址 。in 限定 符 可 以 扩 
大 搜索 范围 ， 包 含 用 户 的 全 名 : in:fullname,login,email。 此 外 还 有 儿 个 有 用 的 限定 符 ， 
详情 参阅 文档 : https://developer.github.com/v3/search/#search-users。 









































查询 search/users 端点 得 到 的 响应 如 下 : 


{ 

"total_count": 26873， 

"incomplete_results": false, 

"items": [ 

人 

"login": "ben", 
"Ed .39902; 
"avatar_url": "…", 
"gravatar_id": "" 
Th 
"html_url": "", 


"score": 98.24275 
} 
{ 


"login": "bengottlieb", 
"id": 53162， 





大 
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"avatar_url": " 
"gravatar_id": "" 
"url" 了 山 1 
"html_url": " 


"score": 35.834213 
]， 
] 
} 




















这 里 的 元 素 列 表 是 查询 users/<name> 端点 得 到 的 结果 。 有 用 的 字段 有 用 户 的 头像 


(avatar_urL) ， 指 向 其 他 API 端点 的 几 个 链接 (repos_url,，ur1)， 
或 组 织 ， 在 type 字段 中 标明 )。 


4.3 ”示例 应 用 


以 及 结果 的 类 型 (用户 


现在 ， 我 们 大 致 了 解 了 Search API 的 行为 ， 下 面 用 它 做 些 有 用 的 事 。 
假设 你 的 开发 团队 把 Git 仓库 存储 在 GitHub 中 ， 而 且 把 运行 应 用 所 需 的 组 件 分 成 多 个 小 仓 





库 。 这 种 情况 对 于 非 技术 类 同事 来 说 相当 环 手 ， 如 果 想 报告 问题 ， 
哪个 仓库 里 ， 而 且 也 不 知道 怎么 查找 报告 过 的 问题 。 











那么 他 们 不 知道 该 发 到 


此 时 可 以 使 用 搜索 ， 但 是 在 组 织 的 所 有 仓库 中 搜索 要 使 用 user:<organization> 运算 符 ， 
而 非 程序 员 遇 到 这 种 情况 时 有 点 害怕 ， 不 能 立即 写 出 运算 符 。 此 外 ， 用 户 每 次 搜索 工 单 时 





都 要 记得 添加 这 个 选项 。 








Search API 能 稍微 简化 这 种 操作 。 我 们 将 构建 一 个 GUI 应 用 ， 界 





看 中 只 有 一 个 搜索 框 ， 这 








样 非 技术 类 用 户 能 特别 轻易 地 搜索 某 个 组 织 中 所 有 仓库 的 所 有 工 单 。 最 终 构建 得 到 的 应 用 











如 图 4-1、 图 4-2 和 图 4-3 所 示 。 
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Filter API Refactoring 


Changed ‘Filter’ to ashort lived, per-file entity. 


ff a repository/odb has an alternates file wefollow it to grab objects from other repositories. But we don 


Expose Diff Hunks in API 


Rather than doing string parsing, |'d prefer having diff hunks available to mess with. 


SshCredentials API implementation 


o, this revolves around implementing SSH interactive only, right? 


The API have some problems 7m4a 
![qq 20150401191153](https://cloud.githubusercontent.com/assets/5475231/6939844/1c570322-d8a3-11¢ 


git push api support 


Now with libgit2 0.19.0 being tagged, it would be cool if we could have git push api support in php-git :) 


dd APl to precompile all diff drivers 














图 4-1: 在 Windows 中 运行 搜索 GitHub 的 应 用 





@@ 昌 @ GitHub lssue Search 


libgit2 Bl | ] Search 


Filter API Refactoring 
Changed `Filter to a short lived, per-file entity. 
































Alternates API 
If a repository/odb has an alternates file, we follow it to grab objects from other repositories 


Expose Diff Hunks in API 
Rather than doing string parsing, I'd prefer having diff hunks available to mess with . 


SshCredentials API implementation 
So, this revolves around implementing SSH interactive only, right? 


The APlI have some problems i 
!qq 20150401191153](https://cloud.githubusercontent.com/assets/5475231/6939844/1c57! 


git push api support 
Now with libgit2 0.19.0 being tagged, it would be cool if we could have git push api support 


Add APl to precompile all diff drivers 
While checking out the latest issues mentioned in #813, 1 wanted a way to compile all of the 


Add callback typedefs to the API documentation. 
Callback typedefs are not being put in the documentation. E.g.: https://libgit2.github.com/lit 














图 4-2: 在 Mac 中 运行 搜索 GitHub 的 应 用 
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邮 





GitHub Issue Search 





libgit2 记 |api Search 





Filter API Refactoring 
Changed `Filter to a short lived, per-file entity. 


Alternates API 


Ifa repository/odb has an alternates file, we follow it to grab objects from other repo 


Expose Diff Hunks in API 


Rather than doing string parsing, I"d prefer having diff hunks available to mess with. 


sshCredentials API implementation 
So, this revolves around implementing SSH interactive only, right? 











The API have some problems i 
![qq 20150401191153](https://cloud.githubusercontent.com/assets/5475231/6939844/ 





git push api support 


Now with libgit2 0.19.0 being tagged, it would be cool if we could have git push api supp 


Add APl to precompile all diff drivers 


While checking out the latest issues mentioned in #813, | wanted a way to compile all of 


7 Sf a ~ ee a 














4-3: 在 Linux 中 运行 搜索 GitHub 的 应 用 


用 户 流 


以 上 是 最 终 目标 ， 下 面 分 析 这 个 应 用 的 用 户 体验 。 


首先 ， 我 们 要 让 用 户 使 用 GitHub 凭据 登录 。 为 什么 ?部 分 原因 是 Search API 有 特别 严格 
的 限 流 措施 ， 而 且 验 证 身份 的 用 户 具 有 更 高 的 频率 限制 。 此 外 ， 还 因为 要 让 用 户 搜索 私有 
仓库 的 工 单 。 为 了 简化 验证 过 程 ， 我 们 的 程序 首先 尝试 从 Git 的 凭据 库 中 获取 GitHub 凭 


























据 ， 如 果 不 成 功 再 显示 登录 表单 ， 如 图 4-4 所 示 。 

















OOe@ GitHub lssue Search 


Username: | 


Password (or token): 


Login 














4-4: 登录 界面 
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用 户 登 录 后 ， 会 显示 一 个 搜索 框 。 输 入 搜索 词 条 ， 然 后 按 回 车 键 ， 界 面 中 会 显示 一 个 滚动 
列表 ， 列 出 搜索 结果 ， 显 示 工 单 的 标题 和 描述 的 第 一 行内 容 。 点 击 某 个 搜索 结果 后 ， 在 用 
户 的 浏览 器 中 打开 对 应 的 工 单 。 
































就 这 么 简单 。 对 用 户 来 说 ， 这 个 应 用 只 有 两 个 主 界面 。 这 是 一 个 简单 而 专注 的 工具 ， 用 于 
解决 十 分 明确 的 问题 ， 因 此 代码 应 该 不 太 难 。 




















4.4 Python 
现在 我 们 知道 这 个 程序 的 行为 了 ， 接 下 来 要 决定 怎么 实现 。 


基于 以 下 几 个 原因 ， 我 们 将 使 用 Python 语言 实现 。 首 先 ， 目 前 为 止 本 书 还 未 提 到 这 门 语 
言 ， 而 我 想 让 你 接触 各 种 语言 。 本 书 的 目标 之 一 是 带 着 读者 探索 之 前 未 曾 见 过 的 技术 。 

















其 次 ， 有 个 用 于 构建 GUI 应 用 的 Python 库 ， 无 需 修 改 就 能 在 Mac OS X、Linux 和 
Windows 中 运行 。 对 一 门 现代 的 高 级 编程 语言 来 说 ， 具 有 如 此 独特 的 功能 真是 让 人 惊喜 。 
如 果 想 通过 别 的 技术 实现 兼容 性 ， 往 往 要 使 用 十 分 复杂 的 框架 、 底 层 语言 (如 C++)， 或 
者 二 者 兼用 。 

最 后 ， 使 用 Python 构建 的 应 用 易于 分 发 。 有 个 Python 包 能 把 整个 Python 程序 及 其 所 有 的 
依赖 打包 成 一 个 文件 (在 OS X 中 打包 成 .app 文件 )。 因 此 ， 若 想 把 这 个 程序 提供 给 同事 ， 
通过 电子 邮件 发 送 一 个 ZIP 文件 即 可 。 这 对 我 们 的 案例 而 言 是 有 帮助 的 ， 因 为 非 技 术 类 用 
户 可 能 并 不 乐于 使 用 安装 程序 (有 时 甚至 无 权 在 设备 中 安装 程序 ) 。 


下 面 概览 编写 这 个 应 用 的 代码 要 使 用 的 库 。 稍 后 会 说 明 具 体 怎么 用 ， 在 此 之 前 先 概览 一 下 
有 助 于 理解 各 个 库 的 作用 。 使 用 Python 做 开发 往往 会 遇 到 这 样 的 窘境 : 不 同 包 的 安装 方式 
不 同 ， 所 以 我 还 会 说 明 如 何 安装 各 个 库 。 













































































4.4.1 AGitHub 


首先 介绍 与 GitHub API 交互 的 库 ， 即 agithub。 这 个 库 抽象 的 层次 不 深 它 把 GitHub 的 
REST API 转换 成 在 对 象 上 调用 的 方法 ， 写 出 的 代码 优雅 且 易 于 阅读 。 

















agithub 库 的 项 目地 址 是 https://github.com/jpaugh/agithub， 安 装 方法 很 简单 ， 只 需 下 载 一 份 
agithub.py 源码 文件 的 副本 ， 与 项 目的 文件 放 在 一 起 即 可 。 











4.4.2 WxPython 

WxPython 用 于 创建 应 用 的 图 形 界面 。 这 个 库 使 用 Python 对 低层 的 WxWidgets 工具 包 做 
了 面向 对 象 抽 象 。WxWidgets 是 原生 UI 工具 包 的 通用 代码 适配器 ， 支 持 Linux、Mac 和 
Windows 操作 系统 的 原生 控件 ， 因 此 可 以 使 用 相同 的 Python 代码 与 这 些 平台 交互 。 
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WxPython 项 目的 网 站 是 http:Wwww.wxpython.org， 那 里 有 详细 信息 。 页 面 的 左手 边 有 针对 
各 个 平台 的 下 载 链接 。 下 一 版 WxPython (代号 “Phoenix”) 将 能 通过 pip 安装， 不 过 写作 
本 书 时 Phoenix 只 有 预先 发 布 版 ， 尚 不 稳定 ， 最 好 别 用 。 





稍微 说 一 下 Python 的 背景 。 现 在 ，Python 处 于 过 渡 期 ， 有 两 个 广泛 使 用 的 版 
本 ， 即 Python 2.7 和 Python 3 (写作 本 书 时 是 3.5 版 )。 这 里 你 无 须 关 心 两 个 
版 本 之 间 的 大 多 数 差 异 细节 ， 如 果 想 跟着 这 个 示例 一 起 做 ， 那 就 使 用 Python 
2.7， 因 为 WxPython 目前 尚 不 支持 Python 3。 即 将 发 布 的 Phoenix 计划 支持 
Python 3。 不 过 编写 后 文 的 代码 时 考虑 了 向 前 兼容 ， 因 此 如 果 你 阅读 本 书 时 
Phoenix 已 经 发 布 ， 在 Python 3 中 运行 也 不 会 遇 到 什么 问题 。 

















4.4.3 Pylnstaller 


PyIstaller 是 我 们 要 使 用 的 分 发 工具 。 这 个 程序 的 主要 功能 是 读 取 Python 代码 ， 然 后 分 
析 ， 找 出 全 部 依赖 ， 最 后 把 所 有 文件 〈 包 括 Python 解释 器 ) 放 和 一 个 目录 里 。 这 个 程序 甚 
至 还 能 打包 那个 目录 ， 这 样 双击 包 就 能 运行 程序 。 所 有 这 些 操作 无 需 过 多 人 工 干预， 配置 
选项 也 没 几 个 。 写 过 GUI 应 用 的 人 都 知道 这 些 问 题 很 难处 理 。 

















如 果 想 了 解 这 个 项 目的 信息 ， 请 访问 http://pythonhosted.org/PyInstaller。 这 个 程序 可 以 使 用 
Python 的 包 管 理 器 安装 ， 方 法 是 执行 pip install pyinstaller 命令 。 


4.5 编写 代码 


好 了 ， 现 在 我 们 知道 要 使 用 Python 生态 系统 中 的 哪些 库 了 。 下 面 开始 编写 代码 ， 利 用 那些 
库 构建 一 个 应 用 。 首 先 ， 编 写 下 述 骨 架 文 件 。 























#!/usr/bin/env python © 


import os, subprocess 
import wx 
from agithub import Github @ 


class SearchFrame(wx.Frame): © 
pass 

if _name == '__main _':@ 

app = wx.App() © 

SearchFrame(None) 

app.MainLoop() 


注意 以 下 几 点 。 


@ #! 字符 序列 表明 这 是 一 个 Python 2.7 程序 。 
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@ 导入 要 使 用 的 库 。 我 们 把 WxPython (wx) 全 部 导入 ， 但 是 对 agithub 来 说 ， 只 需要 
Github 类 (注意 大 小 写 )。os 和 subprocess 出 自 Python 标准 库 。 

@ 这 是 实现 主 窗 口 的 类 。 讨 论 具 体 的 实现 时 再 细 说 。 

在 Python 中 要 使 用 这 种 句法 创建 应 用 的 主 入 口 点 。 

日 在 WxPython 中 ， 主 函数 要 这 么 写 。 我 们 实例 化 一 个 App 实例 ， 创 建 顶层 窗 体 的 实例 ， 
然后 运行 应 用 的 主 循环 。 

下 载运 行 这 个 程序 ， 你 会 看 到 命令 行 挂 起 了 ， 其 实 它 是 在 等 待 GUI 输入 。 这 是 因为 wx 库 

无 法 创建 没有 内 容 的 窗 体 ， 下 面 我 们 来 修正 这 个 问题 ， 不 过 在 此 之 前 先 岔 个 题 ， 了 解 一 些 

Git 的 内 部 机 制 ， 以 便 提升 用 户 体验 。 





© 



































4.5.1 ”获取 Git 凭 据 的 辅助 函数 
前 面 的 代码 清单 是 大 多 数 UI 代码 的 基本 结构 ， 在 实现 具体 细节 之 前 应 该 定义 一 个 函数 ， 
获取 用 户 的 GitHub 凭据 。 我 们 会 取 个 巧 ， 先 询问 Git 有 没有 保存 用 户 的 登录 名 和 密码 


为 此 ， 要 使 用 git credential fill 命令 。Git 内 部 就 是 这 么 做 的 ， 这 样 与 GitHub 中 的 远程 
仓库 交互 时 无 需 用 户 每 次 都 输入 GitHub 网 站 的 密码 。 这 个 命令 的 运作 方式 是 ， 从 stdin 
中 以 <key>=<value> 格式 接收 关于 连接 的 所 有 信息 ， 调 用 方 提供 所 需 的 全 部 信息 后 ， 关 闭 
stdin 流 (或 者 输出 一 个 空 行 )， 然 后 Git 输出 所 获 的 关于 连接 的 全 部 信息 。 运 气 好 的 话 ， 
这 些 信息 中 会 有 用 户 的 登录 名 和 密码 。 整 个 交互 过 程 有 点 像 下 面 这 样 : 





















































$ echo "host=github.com" | git credential fill @ 
host=github. com 

username=ben @ 

password=(redacted) 


@ 把 一 行 输入 传 给 git credential， 然 后 关闭 stdin， 告 诉 Git 输入 结束 。 


@ Git 输 出 所 获 的 关于 连接 的 全 部 信息 ， 包 括 输入 的 值 ， 以 及 用 户 名 和 密码 (如果 Git 知 
道 的 话 )。 




















关于 git-credential 命令 还 有 一 点 要 知道 : 如 果 它 对 主机 一 无 所 知 ， 那 么 它 会 在 终端 询 
问 用 户 。 这 一 行为 对 GUI 应 用 不 友好 ， 因 此 我 们 会 使 用 GIT_ASKPASS 环境 变量 来 禁用 这 
个 功能 。 














这 个 辅助 函数 的 代码 如 下 : 





GITHUB_HOST = "github.com' 
def git_ credentials(): 
os.environ['GIT_ASKPASS'] = 'true' @ 
p = subprocess.Popen(['git', 'credential', 'fill'], 
stdout=subprocess .PIPE, 





stdin=subprocess.PIPE) @ 


stdout, stderr = p.communicate('host={}\n\n' 


creds = {} 


for Line in stdout.split('\n')[:- 


k,v = line.split('=" 
creds[k] = v 
return creds © 


























.format(GITHUB_HOST)) © 


1]:@ 


















































@ 我 们 把 6IT_ASKPASS 设 为 字符 串 'true'。Unix 程序 都 理解 这 种 做 法 ， 这 里 的 作用 是 让 
git-credential 不 向 用 户 询问 凭据 。 

@ 在 Python 中 若 想 使 用 stdin 和 stdout， 要 使 用 subprocess.Popen 运行 程序 。 第 一 个 参 
数 是 一 个 列表 ， 列 出 传 给 程序 的 参数 ， 后 两 个 参数 指明 我 们 要 捕获 stdin 和 stdout。 
@ p.communicate 的 作用 是 写 入 stdin， 以 及 返回 stdout 中 的 内 容 。 这 个 方法 还 能 返回 

stderr 中 的 内 容 ， 不 过 这 个 程序 将 其 忽略 了 。 
@ 处 理 stdout 0 在 = 字符 处 拆 分 各 行 ， 然 后 存 入 字典 。 
日 因此 ， 这 个 函数 的 返回 值 是 一 个 字典 ， 存 储 着 'username' 和 'password' 值 。 真 便利 | 








4.5.2 ”窗口 和 界面 
好 的 ， 现 在 我 们 能 跳 
体 ， 向 这 个 目标 靠近 


跳 过 登录 界面 了 ， 但 是 


还 没 办 法 向 用 户 显示 登录 界面 。 下 面 实现 主 窗 


0 


的 作用 概述 


class SearchFrame(wx.Frame): 
def _ iinit_ (self, *args, **kwargs): © 
kwargs.setdefault('size', (600,500)) 
wx.Frame.__init (self, *args, **kwargs) 


self.credentials = {} 
self.orgs = [] 


self.create_controls() 
self.do_layout() 
self.SetTitle('GitHub Issue Search') 


# 先 尝试 从 Git 的 缓存 中 加 载 凭据 

self.credentials = git _ credentials() 

if self.test_credentials(): 
self.switch to_search_panel() 





self.Show() 





这 里 有 几 处 句法 你 可 能 
个 参数 。 这 里 内 MF 需 知 道 首 捕 


不 理解 。 





*args 和 **kwargs 的 作用 是 捕获 多 个 实 参 ， 























方法 是 构造 方法 ， 因 此 主 函 数 调 用 SearchFrame() 时 从 这 
术 如 下 〈 稍 后 详解 ) 。 


-LEE = 











将 其 放 入 一 





里 开始 运行 。 这 


获 这 些 参数 的 目的 是 为 了 传 给 两 行 之 后 的 父 类 构造 方法 。 


个 方法 
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(1) 设 置 布局 尺寸 ， 将 其 传 给 父 类 的 构造 方法 。 
(2) 创建 UI 控件 。 
(3) 使 用 前 面 实现 的 辅助 函数 获取 用 户 的 登录 凭据 。 
(4) 修改 标题 ， 向 用 户 显示 应 用 。 




















在 说 明 这 几 点 的 实现 方式 之 前 ， 我 们 先 回 过 头 来 说 说 这 个 类 的 作用 。 这 个 类 负责 维护 顶层 
窗 体 ( 带 有 标题 栏 、 菜 单 等 的 窗口 )， 决 定 在 窗 体 中 显示 什么 。 这 里 ， 我 们 想 先 显示 登录 
UI， 获 得 有 效 的 凭据 后 (从 Git 的 缓存 获取 ， 或 者 由 用 户 输 入 ) ， 切 换 到 搜索 UI。 


好 了 ， 背 景 知识 够 了 。 下 面 来 看 获取 和 检查 凭据 的 代码 。 








def login_accepted(self, username, password): 
self.credentials['username'] = Username 
self.credentials['password'] = password 
if self.test_credentials(): 
self.switch to_search_panel() 


def test_credentials(self): 

if any(k not in self.credentials for k in ['username', 'password']): 
return False 

g = Github(self.credentials['username'], self.credentials['password']) 

status ,data = g.user.orgs.get() @ 

if status != 200: 
print('bad credentials in store') 
return False 

self.orgs = [of['login'] for o in data] @ 

return True 


def switch_to_search_panel(self): 
self.login panel.Destroy() 
self.search_panel = SearchPaneL(seLf， 
orgs=self .orgs, 
credentials=self.credentials) 
self.sizer.Add(self.search_panel, 1, flag=wx.EXPAND | wx.ALL, border=10) 
self.sizer.Layout() 


@ agithub 库 中 的 每 个 函数 都 返回 两 个 值 。 在 Python 中 可 以 使 用 a,b = <expr> 句法 直接 
把 两 个 值 绑 定 给 两 个 变量 。 

@ agithub 库 会 把 API 返回 的 JSON 解码 成 Python 字典 。 这 里 ， 我 们 只 对 组 织 的 名 称 感 兴 
趣 ， 因 此 我 们 使 用 列表 推导 (list comprehension) ， 告 诉 Python 只 保存 data 列表 中 各 个 
字典 里 的 "login" 字段 。 

















这 三 个 方法 在 程序 执行 过 程 的 不 同时 刻 运 行 。 如 果 和 凭据 从 Git 中 读 取 ， 立 即 运 行 test_ 
credentials 方法 ; 如果 在 登录 面板 中 输入 (参见 4.5.3 节 )， 先 运行 login_accepted 回调 ， 
然后 再 调用 test_credentials。 


























不 管 怎么 运行 ， 我 们 的 目的 都 是 获取 用 户 所 属 的 组 织 列表 ， 测 试 这 些 方 法 是 否 能 用 。 从 这 
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段 代 码 可 以 看 出 agithub 库 的 使 用 方式 : URL 路 径 对 应 于 Github 类 实例 上 的 对 象 - 属性 
表示 法 ，HTTP 动词 对 应 于 方法 调用 ; 返回 值 是 一 个 字典 对 象 ， 包 含 状 态 码 和 数据 。 如 有 果 
请 求 失败 ， 即 返回 的 状态 码 不 是 20， 向 用 户 显示 登录 面板 。 如 果 成 功 ， 调 用 switch_to_ 
search_panel 方法 。 








我 们 在 UI 线程 中 所 做 的 是 同步 网 络 调用 。 通 常 这 么 做 不 好 ， 因 为 在 处 理 完 
网 络 调用 之 前 UI 不 会 有 反应 。 理 想 的 处 理 方式 是 ， 把 网 络 调用 移 到 另 一 个 
线程 中 ， 得 到 返回 值 后 发 出 消息 。 可 是 ， 这 样 做 会 增加 本 章 的 长 度 和 难度 ， 
而 本 章 已 经 很 长 很 难 了 ， 因 此 没有 涉及 这 些 高 级 话题 。 希 望 你 能 原谅 我 们 做 
了 这 样 的 简化 。 对 这 个 案例 来 说 ， 使 用 同步 代码 完全 没 问 题 。 


























最 后 一 个 方法 用 于 转换 UI。 登 录 面板 被 两 个 对 象 引用 ， 一 个 是 searchFrame 实例 ( 父 级 窗 
口 )， 一 个 是 控制 登录 面板 布局 的 布局 管理 器 (sizer)。 幸 好 ， 调 用 Destroy() 方法 能 去 除 


这 两 个 引用 ， 

















所 以 此 后 可 以 创建 SearchPanel 实例 ， 再 把 它 添加 到 布局 管理 器 中 。 此 后 还 











要 在 布局 管理 器 上 调用 Layout() 方法 ， 否 则 布局 管理 器 不 会 调整 新 面板 的 位 置 和 尺寸 。 














def create_controls(self): 


def 


# 创建 菜单 。 主 要 用 于 在 0S Xx 中 实现 "Cmd-Q" 快 捷 键 
fiLLemenu = wx.Menu() 
filemenu.Append(wx.ID_EXIT, '&Exit') 

menuBar = wx.MenuBar() 

menuBar .Append(filemenyu, '&File') 
self.SetMenuBar (menuBar) 








# 实例 化 登录 UI 
self.login panel = LoginpPanel(self, onlogin=self.login_ accepted) 


do_layout(self): 

self.sizer = wx.BoxSizer(wx.VERTICAL) 

self.sizer.Add(self.login panel, 1, flag=wx.EXPAND | wx.ALL, border=10) 
self.SetSizer(self.sizer) 


create_controls 方法 的 作用 相当 简单 ， 先 实例 化 一 个 只 包含 “File 一 Exit” 的 菜单 ， 然 后 
实例 化 登录 面板 (后 文 说 明 实 现 方式 )。 注 意 ， 创 建 可 见 的 控件 时 传 给 构造 方法 的 第 一 个 


参数 是 self。 





这 是 因为 我 们 构建 的 SearchFrame 实例 是 那个 控件 的 父 窗 口 。 


do_layout 方法 使 用 WxWidgets 提供 的 布局 管理 器 自动 布局 。 布 局 管理 器 是 个 复杂 的 话题 ， 
不 过 对 于 这 部 分 代码 来 说 只 需要 知道 以 下 几 点 。 








。 BoxSizer 在 一 个 方向 上 堆 受 窗 体 部 件 ， 这 里 是 纵向 堆 登 。 

。 传 给 sizer.Add 方法 的 第 二 个 参数 是 缩放 因子 。 如 果 设 为 零 , 不 管 父 窗口 怎么 改变 尺寸 ， 
窗 体 部 件 的 大 小 始终 不 变 ， 如 果 设 为 任何 非 零 值 ， 布 局 管理 器 控制 的 所 有 控件 会 自动 调 
整 , 填 满 整个 容器 。 这 个 布局 管理 器 中 只 有 一 个 控件 , 不 过 我 们 仍 想 让 它 占 满 整个 窗口 ， 



























































因此 传人 1。 
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。 border 参数 告诉 布局 管理 器 在 窗 体 部 件 周围 留 出 多 少 补 白 空 间 。 

。 wx.EXPAND 标志 告诉 布局 管理 器 ， 在 堆 倒 的 反方 向 上 延伸 窗 休 部件。 这里， 我 们 沿 纵向 
堆 登 ， 不 过 却 想 横向 延伸 窗 体 部 件 。 

。 wx.ALL 标志 指定 在 窗 体 部 件 的 哪 边 留 白 。 


我 们 要 养 成 好 的 习惯 ， 编 写 测试 。 能 自动 验证 的 代码 不 多 ， 不 过 应 该 覆盖 下 面 这 些 。 


























from nose.tooLs import eq_, ok_, raises © 


class TestApp: 
def setUp(seLf): @ 
self.f = None 
self.app = wx.App() 


de 


=h 


tearDown(self): 

if self.f: 
self.f.Destroy() 

self.app.Destroy() 


def test_switching_panels(self): © 
self.f = SearchFrame(None, id=-1) 
# 应 该 出 现 子 面板 ,而 且 类 型 正确 
ok_(isinstance(self.f.login panel, Loginpanel)) 
ok_(isinstance(self.f.search _ panel, SearchPanel)) 
# 已 经 销毁 
raises(RuntimeError, lambda: self.f.login panel.Destroy()) 
# 尚未 销毁 
ok_(self.f.search_panel.Destroy()) 








@ 我 们 使 用 的 测试 工具 是 Nose， 安 装 方法 是 执行 pip install nose 命令 ,运行 方法 是 在 
命令 行 中 输入 nosetests app.py。 这 个 工具 通过 命名 约定 标识 视 坛 和 固件 ， 用 起 来 基本 
上 很 顺手 。 

@ Nose 会 自动 查找 setup 和 tearDown 方法 ， 分 别 在 运行 各 个 测试 之 前 和 之 后 调用 。 这 
里 ， 我 们 使 用 那 两 个 方法 管理 要 测试 的 窗 体 ， 以 及 全 部 窗 体 所 属 的 App 实例 。 

@ 这 是 一 个 测试 方法 ，Nose 会 找到 它 然后 运行 。 我 们 确认 子 面板 的 类 型 是 否 正确 ， 还 确 
认 从 Git 中 获得 凭据 后 是 否 会 自动 过 滤 到 搜索 面板 。 




















就 这 么 简单 ! 除了 管理 几 个 字段 之 外 ， 这 些 代码 基本 上 都 用 于 管理 UI， 这 正 是 UI 类 应 该 
做 的 。 下 面 编 写 两 个 面板 中 的 第 一 个 ， 这 个 面板 会 弹 入 弹出 。 











4.5.3 登录 GitHub 


LoginPanel 类 的 结构 与 SearchFrame 类 相似 ， 不 过 有 几 处 明显 不 同 。 下 面 先 给 出 代码 ， 然 
后 再 说 明 。 








class LoginPaneL(wx.PaneL) : 


def 


def 


def 


def 


__init (self, *args, **kwargs): 
self.callback = kwargs.pop('onlogin', None) 
wx.Panel._ init (self, *args, **kwargs) 


self.create_controls() 
self.do_layout() 


create_controls(self): 

self.userLabel = wx.StaticText(self, label='Username:') 
self.userBox = wx.TextCtrl(self, style=wx.TE_PROCESS_ENTER) 
self.passLabel = wx.StaticText(self, label='Password (or token):') 
self.passBox = wx.TextCtrl(self, style=wx.TE_PROCESS_ENTER) 
self.login = wx.Button(self, label='Login') 

self.error = wx.StaticText(self, label='') 
self.error.SetForegroundColour((200,0,0)) 





# 绑 定 事件 

self.login.Bind(wx.EVT_BUTTON, self.do_login) 
self.userBox.Bind(wx.EVT_TEXT_ENTER, self.do_login) 
self.passBox.Bind(wx.EVT_TEXT_ENTER, self.do_login) 


do_layout(self): 
# 使 用 网 格 排 布控 件 
grid = wx.GridBagSizer(3,3) 
grid.Add(self.userLabel, pos=(0,0), 
flag=wx.TOP | wx.LEFT | wx.BOTTOM, border=5) 
grid.Add(self.userBox, pos=(0,1), 
flag=wx.EXPAND | wx.LEFT | wx.RIGHT, border=5) 
grid.Add(self.passLabel, pos=(1,0), 
flag=wx.TOP | wx.LEFT | wx.BOTTOM, border=5) 
grid.Add(self.passBox, pos=(1,1), 
flag=wx.EXPAND | wx.LEFT | wx.RIGHT, border=5) 
grid.Add(self.login, pos=(2,0), span=(1,2), 
flag=wx.EXPAND | wx.LEFT | wx.RIGHT, border=5) 
grid.Add(self.error, pos=(3,0), span=(1,2), 
flag=wx.EXPAND | wx.LEFT | wx.RIGHT, border=5) 
grid.AddGrowableCol(1) 


# 把 网 格 放 在 纵向 中 心 

vbox = wx.BoxSizer(wx.VERTICAL) 
vbox.Add((0,0), 1) 
vbox.Add(grid, ©0, wx.EXPAND) 
vbox.Add((0,0), 2) 
self.SetSizer(vbox) 





do_login(self, _): 
U = self.userBox.GetValue() 
p = self.passBox.GetValue() 
g = Github(u, p) 
status ,data = g.issues.get() 
if status != 200: 
self.error.SetLabel('ERROR: ' + data[ 'message']) 
elif callable(self.callback): 
self.callback(u, p) 
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你 可 能 还 记得 ， 在 SearchFrame 


其 中 有 些 结构 与 前 面 的 代码 类 似 。 先 从 构造 方法 说 起 。 





类 的 create_controls 方法 中 创建 这 个 面板 时 传人 了 一 个 关 











键 字 参数 : LoginPaneL(seLf，ontLogin=seLf.Login_accepted)。 定 义 构 造 方法 时 ， 我 们 把 那 








个 回调 取出 保存 ， 留 待 后 用 。 随 后 ， 调 用 两 个 其 他 函数 ， 构 建 布局 ， 然 后 返回 。 





create_controls 方法 比 SearchFrame 类 的 版 本 内 容 多 一 些 ， 因 为 这 个 面板 的 控件 更 多 。 我 
们 分 别 使 用 一 行 代码 创 建 静态 文本 、 文 本 输入 框 和 按钮 控件 。wx .TE_PROCESS_ENTER 样式 告 





诉 WxPython 库 ， 当 光标 位 于 文 

















本 框 内 时 ， 如 果 用 户 按 下 回 车 键 ， 那 么 就 触发 一 个 事件 。 





接 下 来 的 一 段 代 码 把 控件 事件 绑 定 到 方法 调用 上 。 在 WxPython 中 每 次 触发 事件 时 都 会 传 
给 处 理 程序 一 个 参数 ， 这 个 参数 是 包含 事件 相关 信息 的 对 象 。 因 此 ， 同 一 个 国 数 可 以 处 理 
任何 一 种 事件 。 这 里 ， 两 个 文本 框 对 ENTER 事件 的 处 理 程序 ， 以 及 按钮 对 BUTTON 事件 的 处 














理 程序 都 是 seLf.do_Login。 


















































件 ， 而 且 行 或 列 可 以 拉 人 1 











do_layout 方法 使 用 的 布局 管理 器 与 
布局 管理 器 相关 的 话题 不 在 本 书 范畴 之 内 ， 你 只 需 知道 这 种 布局 管理 器 在 网 格 中 排 布 控 
以 填 满 容器 。 这 里 ， 我 们 使 用 pos=(r,c) 表示 法 把 控件 放 在 各 


5 之 前 不 同 ， 这 里 用 的 是 GridBagSizer 实例 。 再 次 重申 ， 














自 的 位 置 上 (与 大 多 数 坐 标 系 不 同 ， 这 里 要 先 指定 所 在 的 “ 行 ”)， 然 后 通过 span 参数 让 控 
件 横 跨 两 列 。flags 和 border 参数 的 作用 基本 与 前 面 一 样 ，AddGrowableCol 函数 告知 布局 引 





擎 允许 网 格 的 哪些 部 分 拉 伸 。 














然后 我 们 做 了 件 奇怪 的 事 ; 把 GridBagstzer 实例 放 到 另 一 个 布局 管理 器 中 。 髓 套 布局 管理 








器 是 个 强大 的 功能 ， 几 乎 能 实现 任何 窗口 布局 ， 不 过 实现 起 来 可 能 不 太 容 易 。 这 个 纵向 的 


BoxSizer 实例 也 包含 几 个 直接 他 
把 包含 所 有 控件 的 那个 布局 管理 
之 一 处 。 效 果 如 图 4-5 所 示 。 





| 建 的 元 组 ， 这 种 特殊 的 形式 用 于 添加 间隔 区 。 这 里 ， 我 们 
器 放 在 两 个 比例 不 同 的 间隔 区 之 间 ， 距 离 窗 口上 部 约 三 分 














Loon 











4-5: 登录 UI 的 尺寸 变化 行为 
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最 后 是 do_Login 方法 。 先 测试 填写 的 凭据 是 否 正 确 ， 如 有 果 正 确 ， 把 凭据 传 给 构造 时 设置 的 
回调 ， 如 果 不 正确 ， 设 置 一 个 标注 的 文本 ， 这 个 标注 的 前 景色 是 带 有 阴影 的 红色 ， 起 到 警 
醒 作 用 。 


下 面 大 致 测试 这 个 行为 。 同 样 ， 这 个 类 除了 创建 WxPython 控件 之 外 没 做 什么 ， 不 过 可 以 
在 测试 类 中 加 入 下 述 方法 ， 以 确认 登录 失败 后 会 显示 错误 消息 。 











def test_login panel(self): 
self.f = wx.Frame(None) 
Lp = Loginpanel(self.f) 
eq_(lp.error.GetLabelText(), '') 
lp.do_login(None) 
ok_(lp.error.GetLabelText().startswith('ERROR')) 


4.5.4 ”搜索 GitHub 
用 户 成 功 登 录 后 ， 销 毁 LoginPanel 实例 ， 显 示 搜 索 面板 (SearchPaneL) : 


class SearchPanel(wx.Panel): 
def _ iinit (self, *args, **kwargs): 
self.orgs = kwargs.pop('orgs', []) 
self.credentials = kwargs.pop('credentials', {}) © 
wx.Panel._ init (self, *args, **kwargs) 


self.create_controls() 
self.do_layout() 


def create_controls(self): 
self.results_panel = None 
self.orgChoice = wx.Choice(self, choices=self.orgs, style=wx.CB_SORT) 
self.searchTerm = wx.TextCtrl(self, style=wx.TE_PROCESS_ENTER) 
self.searchTerm.SetFocus() 
self.searchButton = wx.Button(self, label="Search") 





# 绑 定 事件 @ 
self.searchButton.Bind(wx.EVT_BUTTON, self.do_search) 
self.searchTerm.Bind(wx.EVT_TEXT_ENTER, self.do_search) 


def do_layout(self): 
# 横向 排列 选择 框 . 搜 索 框 和 按钮 
hbox = wx.BoxSizer(wx.HORIZONTAL) 
hbox.Add(self .orgChoice, 0, wx.EXPAND) 
hbox.Add(self.searchTerm, 1, wx.EXPAND | wx.LEFT, 5) 
hbox.Add(self.searchButton, 0, wx.EXPAND | wx.LEFT, 5) 








# 把 所 有 控件 移 到 顶部 , 留 出 空间 显示 结果 
self.vbox = wx.BoxSizer (wx.VERTICAL) 
self.vbox.Add(hbox, 0, wx.EXPAND) © 
self.SetSizer(self.vbox) 





def do_search(self, event): 
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term = self.searchTerm.GetValue() 
org = self.orgChoice.GetString(self.orgChoice.GetCurrentSelection()) 
g = Github(self.credentials['username'], self.credentials['password']) 
code,data = g.search.issues.get(q="user:{} {}".format(org, term)) @ 
if code != 200: 

self.display_error(code, data) 
else: 

seLf .dispLay_resuLts(data['items ']) 


def display_results(self, results): © 
if self.results_panel: 
self.results_panel.Destroy() 
self.results_panel = SearchResultspPanel(self, -1, results=results) 
self.vbox.Add(self.results_panel, 1, wx.EXPAND | wx.TOP, 5) 
self.vbox.Layout() 


def display_error(self, code, data): @ 
if self.results_panel: 
self.results_panel.Destroy() 
if 'errors' in data: 
str = ''.join('\n\n{}'.format(e['message']) for e in data['errors']) 
else: 
str = data[ 'message'] 
seLf .resuLts_paneL = wx.StaticText(self, label=str) 
seLf .resuLts_paneL.SetForegroundCoLour((200,0,0)) 
self.vbox.Add(self.results_panel, 1, wx.EXPAND | wx.TOP, 5) 
self.vbox.Layout() 
width = self.results_panel.GetSize().x 
self.results_panel .Wrap(width) 


这 个 类 的 代码 有 点 多 ， 不 过 有 些 是 见 过 的 。 我 们 不 一 一 详 述 ， 下 面 介绍 儿 个 有 趣 的 功能 。 








TT 


@ 创建 这 个 面板 时 ， 我 们 通过 关键 字 参 数 传 和 用户 的 凭据 和 组 织 列表 ， 因 此 这 些 信息 胡 
kwargs 字典 中 。 这 里 ， 我 们 使 用 pop 方法 取出 父 类 的 构造 方法 不 理解 的 值 。 

@ 既 捕 获 搜索 按钮 的 “点 击 ” 事 件 ， 又 捕获 文本 框 的 “ 回 车 键 ” 事 件 。 二 者 都 能 触发 
搜索 。 

@ 把 搜索 栏 添加 到 布局 管理 器 中 时 ， 我 们 把 缩放 因子 设 为 0。 因此 ， 有 多 余 空间 时 搜索 框 
不 会 延伸 ， 而 是 保持 尺寸 不 变 ， 为 后 面 添 加 的 结果 面板 留 出 空间 。 

@ 执行 搜索 操作 。 首 先 歼 取 搜 索 词 条 和 组 织 ， 然 后 将 其 传 给 agithub 实例 ， 返 回 结果 和 
HTTP 状态 码 。 

@ 把 搜索 结果 传 给 另 一 个 类 ， 然 后 把 那个 类 的 实例 添加 到 主 布局 管理 器 中 ， 并 且 在 参数 
中 指明 ， 填 满 余下 的 可 用 空间 。 

@ 如 果 搜 索 出 错 ， 那 么 使 用 这 个 方法 把 错误 显示 出 来 。 其 中 有 几 行 代码 根据 搜索 面板 的 
既定 宽度 调整 文本 的 换行 宽度 。 这 种 方式 不 是 很 好 ， 更 好 的 处 理 方式 留 作 练习 ， 由 读 
者 完成 。 


















































































































































同样 ， 代 码 虽 多 ,但 是 大 多 数 都 见 过 。 和 覆盖 上 述 代码 的 测试 代码 如 下 : 








66 | 第 4 章 


def test_search_paneL(seLf ) : 
seLf.f = wx.Frame(None) 
sp = Searchpanel(self.f, orgs=['a', 'b', 'c']) 
eq_(0, sp.orgChoice.GetCurrentSelection()) 
eq_('a', sp.orgChoice.GetString(0)) 
sp.display_error(400, {'errors': [{'message': 'xyz'}]}) 
ok_(isinstance(sp.results_panel, wx.StaticText)) 
eq_('xyz', sp.results_panel.GetLabelText().strip()) 


村 沪 驴 “显示 结果 


至 此 ， 登 录 面 板 有 了 ， 用 户 也 能 输入 查询 词 条 了 ， 可 是 还 不 能 显示 结果 。 下 面 就 来 解决 这 
个 问题 。 




















了 














获得 搜索 结果 后 ， 先 创建 一 个 SearchResultsPanel 实例 ， 然 后 再 创建 
实例 。 下 面 介绍 一 下 这 两 个 类 。 


系列 SearchResult 














cLass SearchResuLtsPaneL(wx.ScroLLtedNWindow): © 
def _init_ (self, *args, **kwargs): 
results = kwargs.pop('results', []) 
wx.PyScrolledWindow.__init__(self, *args, **kwargs) 


# 把 搜索 结果 控件 布局 到 可 滚动 的 区 域 中 
vbox = wx.BoxSizer(wx.VERTICAL) 
if not results: 

vbox.Add(wx.StaticText(self, label="(no results)"), 0, wx.EXPAND) 
for r in results: 

vbox.Add(SearchResult(self, result=r), 

flag=wx.TOP | wx.BOTTOM, border=8) 

self.SetSizer(vbox) 
self.SetScrollbars(0, 4, 0, 0) 


class SearchResult(wx.Panel): 
def _ init_ (self, *args, **kwargs): 
self.result = kwargs.pop('result', {}) 
wx.Panel._ init (self, *args, **kwargs) 


self.create_controls() 
self.do_layout() 


def create_controls(self): @ 
titlestr = self.result['title'] 
if self.result['state'] != 'open': 
titlestr += ' ({})'.format(self.result['state']) 
textstr = self.first line(self.result['body']) 
self.title = wx.StaticText(self, label=titlestr) 
seLf .text = wx.StaticText(self, label=textstr) 


# 调整 标题 的 文本 格式 

titleFont = wx.Font(16, wx.FONTFAMILY_DEFAULT, 
wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_BOLD) 

self.title.SetFont(titleFont) 
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# 在 这 整个 控件 上 绑 定 点 击 和 悬 停 事件 @ 
self.Bind(wx.EVT_LEFT_UP, self.on click) 
self.Bind(wx.EVT_ENTER_WINDOW, self.enter) 
self.Bind(wx.EVT_LEAVE_WINDOW, self.leave) 





def do_layout(self): 
vbox = wx.BoxSizer (wx.VERTICAL) 
vbox.Add(self.title, flag=wx.EXPAND | wx.BOTTOM, border=2) 
vbox.Add(self.text, flag=wx.EXPAND) 
self.SetSizer(vbox) 


=h 


def enter(self, _): 
self.title.SetForegroundColour (wx.BLUE) 


self.text.SetForegroundColour (wx .BLUE) 


=h 


def leave(self, _): 


self.title.SetForegroundColour (wx.BLACK) 
self.text.SetForegroundColour (wx.BLACK) 


def on_click(self, event): @ 
import webbrowser 
webbrowser .open(self.result['html_url']) 


def first_ line(self, body): 
return body.split('\n')[0].strip() or '(no body)’' 


@ 容器 面板 特别 简单 ， 只 有 一 个 构造 方法 。 这 个 类 的 作用 是 壁 放 结果 ， 在 一 个 可 以 滚动 
的 窗口 中 呈现 出 来 。 

@ SearchResult 实例 有 两 个 静态 文本 控件 组 成 ， 分 别 显 示 工 单 的 标题 和 正文 的 第 一 行 。 

@ 我 们 不 仅 为 这 整个 面板 绑 定 了 点 击 事件 ， 还 绑 定 了 鼠标 移入 和 移出 事件 ， 因 此 其 行为 
与 浏览 器 中 的 链接 很 像 。 

@ 这 是 在 Python 中 使 用 默认 训 览 器 打开 URL 的 方式 。 


以 上 就 是 一 个 简单 的 WxPython 应 用 的 代码 。 使 用 这 个 库 要 按照 特定 的 风格 编写 代码 ， 有 
点 繁琐 。 不 过 好 的 一 面 是 ， 这 里 毫 无 隐藏 ， 应 用 的 所 有 布局 都 通过 代码 实现 ， 没 有 看 不 见 
的 戏法 。 此 外 ， 使 用 这 个 库 构 建 的 应 用 无 需 修改 就 能 在 任何 一 台电 脑 中 运行 ， 这 是 一 个 巨 
大 的 优势 。WxPython 可 能 缺少 新 兴 框 架 的 某 些 功能 ， 可 是 它 能 快速 构建 简单 的 跨 平 台 UI， 
这 才 是 重点 。 




































































代码 就 分 析 到 这 里 。 如 果 你 一 直 跟 着 我 做 ， 把 所 有 代码 都 输入 到 一 个 文件 中 了 ， 那 么 现在 
可 以 运行 那个 文件 ， 搜 索 工 单 了 。 然 而 ， 这 个 应 用 是 针对 非 技术 类 用 户 的 。 下 面 看 看 我 们 
能 做 些 什么 ， 让 这 类 用 户 更 易于 上 手 使 用 。 


4.6 打包 


我 们 不 想 让 任何 用 户 安装 Python 2.7 和 一 堆 包 ， 因 此 可 以 使 用 PyInstaller 打包 应 用 ， 得 到 
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易于 分 发 和 运行 的 文件 。 


假设 你 把 前 面 的 代码 都 写 入 search.py 文件 了 ， 而 且 agithub.py 文件 在 同一 个 目录 中 。 让 
PyInstaller 打包 应 用 的 方式 如 下 : 























$ pyinstaller -w search.py 








就 这 么 简单 ! -w 标 志 的 作用 是 让 PyInstaller 创建 带 窗 口 的 应 用 ， 而 不 是 默认 的 控制 台 形 
式 。 在 OS 久 中 ， 上 述 命 令 会 生成 search.app 应 用 包 ， 在 Windows 中 则 生成 search.exe 文 
件 。 你 可 以 把 这 两 个 文件 复制 到 没有 安装 Python 的 电脑 中 ， 它 们 都 能 正常 运行 。 











这 是 因为 PyInstaller 复制 了 运行 程序 所 需 的 一 切 ， 包 括 Python 解析 器 和 代码 文件 本 身 。 执 
行 上 述 命令 生成 的 文件 大 小 为 67MB， 对 这 么 简单 的 程序 来 说 似乎 有 点 大 ,但 是 考虑 到 打 
包 了 如 此 多 的 内 容 ， 这 个 大 小 还 算 说 得 过 去 。 











4.7 小 结 
啊 ， 这 一 章 的 内 容 真 多 呀 ! 现在 休息 一 下 ， 回 顾 所 学 的 知识 。 
本 章 给 出 的 代码 主要 用 于 定义 图 形 界面 。 这 种 任务 所 需 的 代码 都 十 分 繁琐 ， 因 为 这 类 任务 


特别 复杂 。 可 是 ， 有 了 WxPython 之 后 ， 我 们 可 以 使 用 Python 编写 GUI 应 用 ， 写 起 来 不 比 
其 他 工具 包 难 ， 而 且 应 用 能 在 所 有 主流 平台 中 免费 运行 。 


我 们 学 习 了 如 何 使 用 git credential 命令 向 Git 询问 某 个 Git 服务 器 的 凭据 。 这 个 功能 特 
别 强大 ， 除 此 之 外 还 能 定制 凭据 存储 后 台 ， 不 过 我 们 只 了 解 了 皮毛 。 借 助 这 个 功能 ， 我 们 
可 以 顺应 用 户 现 有 的 习惯 ,不 再 一 次 次 向 用 户 询问 相同 的 信息 。 









































我 们 还 学 习 了 如 何 使 用 agithub 库 优雅 地 抽象 HTTP API。 我 们 使 用 对 象 -方法 表示 法 请 
求 搜索 工 单 的 API， 进 行 身 份 验证 和 工 单 搜索 。agithub 库 充 分 考虑 了 向 前 兼容 性 和 惯用 
法 ， 它 把 属性 和 方法 串 接 起 来 构建 查询 URL。 使 用 这 种 方式 也 能 查询 其 他 REST API。 














其 实 ， 本 章 的 要 点 是 学 习 如 何 使 用 GitHub Search API。 我 们 学 习 了 这 个 API 的 一 般 行 为 、 
不 同 的 搜索 类 型 、 解 释 和 排序 结果 的 方式 ， 以 及 如 何 调整 搜索 词 条 ， 减 少 无 关 结 果 的 数 
量 。 掌 握 这 些 知识 后 ， 你 将 能 在 GitHub 或 GitHub Enterprise 中 找到 任何 想 找 的 信息 。 我 们 
还 了 解 到 ，GitHub 网 站 中 的 搜索 UI 是 对 搜索 API 的 简单 包装 ， 所 以 不 管 自己 编写 代码 还 
是 直接 在 浏览 器 中 搜索 ， 都 能 使 用 相同 的 技巧 和 技术 。 


该 换个 话题 了 。 下 一 章 介绍 Commit Status API， 通 过 这 个 API 能 为 Git 仓库 里 的 提交 添 
加 注解 ， 标 上 “好 ”或 “ 坏 ” 标 志 。 下 一 章 中 将 使 用 几 年 前 盛 极 一 时 的 技术 方案 : C# 和 
CLR。 
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往 简单 了 说 ，Git 仓库 就 是 一 长 串 提 交 ， 每 个 提交 都 包含 相当 多 的 信息 : 源码 文件 的 内 容 、 
提交 人 和 提交 时 间 ， 以 及 提交 人 对 改动 的 说 明 ， 等 等 。 这 些 都 是 有 用 的 信息 ， 体 现 了 Git 
的 主要 用 途 ， 即 管理 软件 项 目的 历史 。 





GitHub Commit Status API 为 提交 添加 了 额外 的 元 数据 : 提交 的 各 种 服务 状态 。 这 个 功能 主 
要 把 信息 显示 在 拉 取 请 求 界面 中 ， 如 图 5-1 所 示 。 拉 取 请 求 中 的 每 个 提交 都 有 符号 标明 的 
状态 ， 红 色 “x ”表示 失败 或 错误 ， 绿 色 “v” 表 示 成 功 ， 黄 褐色 “。 表示 正在 判定 中 。 
这 个 功能 在 拉 取 请 求 的 底部 也 有 体现 ， 如 果 分 支 中 最 后 一 个 提交 没有 被 标记 为 成 功 ， 那 么 
你 会 看 到 敬告， 提醒 你 不 要 合并 请 求 。 




















且 ben added some commits 4 minutes ago 


[| Add readme 

团 hdd content x 
Fix a bug 

Fix another bug 


Add more commits by pushing to the branch branch on ben/NancyApplication1. 


@ Waiting to hear about 636e8cb Details 





Merge with caution! 


区 J] 和 Merge pull request 
You can also merge branches on the command line. 











图 5-1: 拉 取 请 求 界面 显示 的 提交 状态 
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显然 ， 这 个 功能 对 持续 集成 服务 最 有 用 。 向 一 个 分 支 中 推送 新 提交 后 ，Jenkins 这 样 的 程序 
会 收 到 通知 ， 然 后 用 新 代码 执行 一 次 构建 /测试 过 程 ， 最 后 通过 提交 状态 API 报告 结果 。 
这 类 应 用 甚至 还 可 以 提供 一 个 链接 ， 指 向 构建 结果 ， 让 用 户 查 明 哪些 测试 失败 了 。 这 个 功 
能 汇聚 了 判断 是 否 接 受 提案 所 需 的 各 种 信息 ， 包 括 改动 了 哪些 代码 、 人 们 的 看 法 如 何 ， 以 
及 改动 是 否 破 坏 了 什么 。 这 些 问 题 的 答案 可 在 同一 页 面 中 找到 ， 即 拉 取 请 求 讨论 页 面 。 









































不 过 ， 构 建 和 测试 只 是 开端 ， 提 交 的 状态 还 有 其 他 用 途 。 例 如 ， 开 源 项 目 通 常 都 有 授权 协 
议 ， 如 果 想 提交 贡献 ， 必 须 签署 这 个 协议 。 这 叫 “ 贡 献 者 授权 协议 ”(Contributor License 
Agreements，CLA)， 通 常会 要 求 你 同意 把 自己 的 贡献 授权 给 项 目的 维护 者 。 可 是 ， 手 工 检 
查 每 个 拉 取 请 求 ， 确 认 作者 是 否 签署 贡献 者 授权 协议 太 麻 烦 ， 此 时 可 以 使 用 类 似 持续 集成 
的 服务 。CLAHub 就 是 这 样 的 服务 ， 它 会 检查 是 否 提交 的 所 有 作者 都 签署 了 贡献 者 授权 协 
议 ， 如 果 没 有 ， 那 么 把 最 后 一 个 提交 标记 为 “错误 ”。 


现在 ， 我 们 知道 这 个 功能 的 目的 和 作用 了 ， 下 面 来 看 如 何 使 用 程序 与 它 交 互 。 



































5.1 Commit Status API 


首先 讨论 访问 控制 。Commit Status API 对 OAuth 的 需求 比 其 他 API 强烈 。 把 仓库 设 为 私 
有 后 ， 我 们 能 完全 控制 哪些 人 或 哪些 应 用 可 以 访问 仓库 。 我 们 会 不 假 思索 地 信任 GitHub 
的 内 部 代码 ， 相 信 它 能 保全 我 们 的 数据 ， 可 是 互联 网 上 的 应 用 呢 ? 借助 OAuth， 我 们 可 以 
为 应 用 赋予 访问 私有 仓库 的 权限 ， 不 过 是 带 有 限制 的 ， 应 用 要 使 用 OAuth 的 作用 域 征询 特 
定 的 权限 ， 不 能 对 数据 肆意 妄 为 。 而 且 ， 这 样 还 能 完全 掌控 各 种 权限 ， 随 时 都 能 取消 应 用 
的 访问 权 。 




















OAuth 系统 使 用 作用 域 管理 权限 ， 应 用 发 出 请 求 ， 被 授予 特定 的 作用 域 之 后 才能 执行 特定 
的 操作 。 访 问 Commit Status API 需要 repo: status 这 个 OAuth 作用 域 ， 授 予 之 后 ， 应 用 可 
以 读 写 提交 状态 ， 不 过 仅 限 于 此 ， 应 用 无 法 访问 仓库 中 的 内 容 。 这 似乎 有 点 奇怪 ， 不 审查 
内 容 怎 么 判断 提交 的 状态 呢 ? 要 知道 ， 这 个 功能 除了 持续 集成 乙 外 还 有 其 他 使 用 场景 ， 也 
就 是 说 应 用 做 判断 时 可 能 不 需要 全 部 访问 权限 。 如 果 服 务 需要 查看 仓库 的 内 容 ， 可 以 请 求 
repo 作用 域 ， 获 得 对 整个 仓库 内 容 (包括 提交 状态 ) 的 读 写 权 限 。 写 作 本 书 时 还 没 办 法 只 
请 求 仓库 的 读 权限 ， 因 此 如 果 一 项 服务 需要 访问 你 的 数据 ， 你 不 得 不 信任 它 ， 为 它 开放 写 
权限 。 





























此 外 ， 这 个 API 也 可 以 匿名 访问 ， 完 全 不 使 用 OAuth。 不 过 ， 此 时 只 能 读 取 公 开 仓 库 的 状 
态 ， 没 有 写 权限 ， 而 且 不 能 访问 私有 仓库 。 


下 表 对 以 上 内 容 做 了 总 结 。 
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OAuth 作 用 域 。 状态 的 访问 权限 。” 仓库 数据 的 访问 权限 
无 (匿名) 只 能 读 公 开 仓 库 ”只 能 读 公开 仓库 
repo:status 读 / 写 无 

repo 读 / 写 读 / 写 


5.1.1 原始 状态 





现在 我 们 知道 如 何 获得 访问 提交 状态 的 权限 了 ， 下 面 来 看 提交 状态 包含 什么 内 容 。 提 交 状 














态 是 原子 实体 ， 每 个 提交 几乎 可 以 有 任意 多 个 状态 〈 数 以 千 计 )。 查 询 现 有 状态 的 方法 是 ， 
向 API 服务 器 中 的 /repos/<user>/<repo>/<re 户 /statuses 端点 发 送 GET 请 求 。 得 到 的 响 


应 是 状态 列表 ， 如 下 所 示 。 


[ 
{ 
"url": "https://api.github.com/repos/*…", 
"id": 224503786 ， 
"state": "success", 
"description": "The Travis CI build passed", 
"target_url": "https://travis-ci.org/libgit2/libgit2/builds/63428108", 
"context": "continuous-integration/travis-ci/push", 
"created_at": "2015-05-21T03:11:022", 
"updated_at": "2015-05-21T03:11:0227" 
}， 
] 














守 守 及 说 明 


其 中 大 多 数字 段 不 言 自 明 ， 不 过 有 几 个 需要 解析 一 下 。 






























































state 值 为 success、failure、error 或 pending 

target_url 为 提交 做 出 某 个 判断 的 URL (这 里 指向 的 是 构建 /测试 日 志 )， 帮 助 用 户 查 明 判 断 依据 

context | 于 把 同一 个 服务 的 多 个 状态 更 新 关联 起 来 ， 各 个 服务 根据 自己 的 规则 设置 这 个 字段 ， 不 
过 对 于 任何 输出 状态 的 过 程 来 说 ， 输 出 pending 状态 和 最 终 状 态 时 要 使 用 相同 的 值 

















HNo 


这 个 API 用 于 获取 原始 数据 ， 不 过 很 快 就 会 变 得 复杂 。 如 何 判 断 提 交 的 状态 是 “好 的 ” 


1 





呢 ? 如 果 有 多 个 状态 且 依 次 为 三 个 待定 状态 、 一 个 成 功 状态 、 一 个 待定 状态 、 两 个 失败 状 
态 和 另 一 个 成 功 状 态 ， 这 时 该 怎么 判断 呢 ? 我 们 可 以 通过 context 字段 把 同一 个 服务 更 新 
的 状态 关联 起 来 ， 然 后 按照 created_at 字段 排序 ， 查 看 各 个 阶段 的 状态 ， 可 是 这 样 工 作 量 
太 大 。 幸 好 ，GitHub API 服务 器 可 以 代劳 。 


5.1.2 合并 后 的 状态 





如 果 向 /repos/<user>/<repo>/<re 户 /status (注意 最 后 一 个 单词 是 单数 ) 发 送 GET 请 求 ， 


那么 获得 的 响应 是 下 面 这 样 的 。 
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"state": "success", 
"statuses": [ 


"url": "https://api.github.com/repos/:…", 


]， 
在 
]， 
"sha" : "6675aaba883952alc1b28390866301ee5c281d37"， 
"total_count": 2， 
"repository": { … }, 
"commit_url": "https://api.github.com/repos/*…", 
"url": "https://api.github.com/repos/*…" 
上 











statuses 字段 中 的 数组 是 需要 你 自己 编写 代码 实现 特定 的 逻辑 得 到 的 结果 ， 它 按照 上 下 文 
合并 状态 ， 只 保留 最 后 一 个 状态 。state 字段 的 值 是 综合 所 有 上 下 文 ， 根 据 下 述 规则 得 出 
的 最 终 状 态 。 


状 态 致 








failure 任 一 上 下 文 输出 failure 或 error 状态 
pending 某 个 上 下 文 的 最 终 状 态 是 pending， 或 者 没有 状态 
success 每 个 上 下 文 的 最 终 状 态 都 是 success 





能 正 是 你 所 需要 的 ， 不 过 如 果 你 的 使 用 场景 需要 其 他 规则 ， 完 全 可 以 使 用 statuses 端 
点 ee 然后 自己 合并 状态 。 





5.1.3 创建 状态 


显然 ， 目 前 提 到 的 状态 都 从 别处 而 来 。 这 个 API 还 支持 创建 状态 ， 方 法 是 向 / 
repos/<user>/<repo>/statuses/<sha> 发 送 POST 请求， 并 在 请 求 中 发 送 一 个 JSON 对 象 ， 
提供 想 包含 在 状态 中 的 字段 。 








字 段 说 明 

state 必须 是 pending、success、error 或 failure (必需 ) 

target_url 指向 判定 状态 详情 的 链接 

description 一 段 简短 的 文字 ， 说 明 为 了 判定 状态 ， 服 务 做 了 什么 

context 各 个 应 用 专用 的 字符 串 ， 以 便 API 管理 多 个 服务 为 同一 个 提交 判定 的 状态 











注意 ， 该 URL 的 最 后 一 部 分 是 <sha>。 查 询 状 态 或 合并 的 状态 使 用 的 是 引用 名 (如 
master ) ， 而 创建 状态 时 要 知道 提交 的 完整 SHA-1 散 列 值 ， 这 样 才能 注解 那个 提交 。 这 是 
为 了 避免 条 件 竞 争 ， 如 果 使 用 引用 ， 处 理 开始 和 结束 时 指向 的 可 能 不 是 同一 个 提交 ， 而 提 
交 的 SHA 永远 不 变 。 
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5.2 编写 一 个 应 用 

好 了 ， 现 在 我 们 知道 如 何 读 写 状态 了 ， 下 面 来 运用 这 个 API。 这 一 节 我 们 将 构建 一 个 简单 
的 HTTP 服务 ， 通 过 OAuth Web 流程 获得 授权 后 ， 为 有 权限 访问 的 仓库 创建 提交 状态 。 我 
们 将 构建 的 这 个 系统 作用 有 限 ， 却 是 以 后 根据 特定 需求 定制 开发 的 良好 起 点 。 


























这 一 次 我 们 使 用 的 语言 是 C#， 运 行 在 CLR (Common Language Runtime， 公 共 语 言 运 行 
时 ) 平台 上 。 在 信息 技术 历史 上 的 某 段 时 期 ， 对 本 书 而 言 这 不 是 好 的 选择 ， 因 为 CLR 只 
能 在 Windows 中 使 用 ， 开 发 工具 价格 不 菲 ， 而 且 C# 语言 和 库 有 相当 大 的 局 限 性 。 然 而 ， 
Mono (.NET 运行 环境 的 开源 实现 ) 出 现 了 ， 这 是 CLR 核心 的 开源 版 ， 而 且 提 供 了 免费 工 
具 ， 因 此 C# 现在 已 被 广泛 接受 ， 对 开源 和 业余 开发 者 来 说 是 相当 不 错 的 技术 选择 。 此 外 ， 
Mono 的 包 生 态 系统 充满 生机 ， 我 们 可 以 利用 现 有 的 库 简 化 我 们 的 工作 。 


5.2.1 要 使 用 的 库 

本 章 不 会 从 头 动手 编写 整个 HTTP 服务 器 。 听 到 这 和 句 话 你 一 定 很 高 兴 。 有 很 多 开源 的 包 能 
为 我 们 代劳 ， 这 个 项 目 要 使 用 的 是 Nancy。 起 初 ，Nancy 项 目 是 作为 Ruby 中 Sinatra 框架 
的 CLR 端口 起 步 的 (项 目 名 称 取 自 Frank Sinatra 的 女儿 Nancy)。 你 会 发 现 这 个 库 的 功能 
非常 强大 ， 同 时 特别 简洁。 

















我 们 也 不 会 直接 实现 访问 GitHub API 的 代码 ， 因 为 GitHub 提供 了 CLR 库 ， 名 为 octokit. 
net。 这 个 库 能 正确 处 理 一 切 操作 ， 而 且 考 虑 到 了 异步 和 类 型 安全 。GitHub 为 Windows 系 
统 开 发 的 客户 端 使 用 的 也 是 这 个 库 ， 所 以 定 能 胜任 这 个 小 应 用 的 需求 。 不 过 ， 这 个 库 对 项 
目的 搭建 有 特殊 的 要 求 : 为 了 正常 运行 ， 必 须 使 用 新 版 CLR (4.5)。 如 果 想 知道 如 何 避免 
受 此 限制 ， 想 跟着 我 一 起 做 ， 请 继续 阅读 下 一 节 。 如 果 你 以 前 用 过 Nancy， 而 且 已 经 安装 
了 NuGet 包 ， 基 本 上 可 以 跳 到 5.2.3 节 。 


























5.2.2 ”开发 环境 
如 果 你 想 跟 着 我 一 起 编写 代码 ， 请 参照 下 文 搭 建 开 发 环境 ， 安 装 所 需 的 全 部 工具 。 搭 建 的 
过 程 在 Windows (使 用 Visual Studio) 和 其 他 平台 (使 用 Xamarin 工具 ) 中 有 所 不 同 。 

















1. Visual Studio 

如 果 你 使 用 的 是 Windows 系统 ， 访 问 https:/www.visualstudio.com/， 下 载 Visual Studio 社 
区 版 。 安 装 程序 会 给 出 众多 选项 ， 而 这 个 示例 只 需要 “Web 开发 者 ”组 件 ， 不 过 你 可 以 根 
据 自 己 的 需求 勾 选 其 他 组 件 。( 如 果 你 购买 了 Visual Studio 的 高 级 版 本 ， 或 者 已 经 安装 了 
Web 开发 相关 的 包 ， 那 就 一 切 就 绪 了 。) 


为 了 让 开发 更 顺利 我 们 要 安装 一 个 插件 一 Nancy 项 目 模 板 。 访 问 https:// 
visualstudiogallery.msdn.microsoft.com/， 然 后 搜索 “nancy.templates”。 在 搜索 结果 中 选择 
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属于 NancyFx 组 织 的 “Nancy.Templates”， 然 后 点 击 “Get Now”。 此 时 会 下 载 一 个 .vsix 文 
件 ， 下 载 完成 后 双击 ， 把 模板 安装 到 Visual Studio 中 。 





下 一 步 ， 使 用 刚才 安装 的 模板 新 建 一 个 项 目 。 进 入 “File 一 New Project” 菜 单 ， 然 后 在 模 
板 列表 中 选择 “Visual C# 一 Web 一 Nancy Application with ASP.NET Hosting”( 如 图 5-2 
所 示 )。 根 据 需 求 调整 底部 的 路 径 和 名 称 ， 然 后 点 击 OK。 

































































New project ? BE 
b Recent NET Fiamework 4.5 Sort by: Default -| 尘 :| 二 Search Installed Templates (Ctrl+E A- 
4 Installed cs 
(= ASP.NET Web Application Visual C# Type: Visual C# 
4 Templates A project for creating a Nancy application 
b Visual Basic 回 Nancy Application with ASP.NET hosting Visual C# ee 
4 Visual C# 
b Store Apps 回 Nancy Application with ASP.NET hosting and Razor Visual C# 
Windows Desktop 
4 Web 四 Nancy Application with self-hosting Visual C# 
Visual Studio 2012 
Cloud Nancy Application with self-hosting and Razor Visual C# 
Reporting 
Silverlight 回 Nancy Demo Application Template Visual C# 
Test 
We 回 Nancy Empty Application with ASP.NET hosting Visual C# 
Workflow 
EE 四 Nancy Empty Application with ASP.NET hosting and Razor = Visual C# 
b Visual F# 
SN Somer 回 Nancy Empty Application with self-hosting Visual C# 
b JavaScript 
Eye Nancy Empty Application with self-hosting and Razor Visual C# 
b TypeScript 
= 
b Online 
Click here to go online and find templates. 
Name: NancyApplication1 
Location: en\ = Browse... 
Solution name: NancyApplication1 | Create directory for solution 
Addto source control 
OK Cancel 





























5-2: 在 Visual Studio 中 创建 一 个 Nancy 应 用 


接 下 来 ， 把 目标 CLR 框架 改 为 Octokit 支持 的 版 本 。 在 Solution Explorer (解决 方案 资源 管 
理 器 ) 中 右键 点 击 项 目 节 点 ， 然 后 选择 “Properties”。 在 Application 选项 卡 中 ， 把 Target 
Framework 设 为 .NET 4.5 (或 以 上 版 本 ) ， 然 后 保存 。 此 后 ， 可 能 会 要 求 你 重新 加 载 这 个 解 
决 方案 。 


最 后 一 步 ， 使 用 NuGet 安装 Nancy 和 Octokit 两 个 包 。 在 解决 方案 资源 管理 器 中 右键 点 
击 项 目 节 点 ， 然 后 选择 “Manage NuGet Packages”。 搜 索 “Nancy”， 如 果 需 要 ， 升 级 ， 基 
为 Nancy 项 目 模 板 指定 的 版 本 可 能 过 时 了 。 然 后 ， 搜 索 “Octokit”， 安 装 。 至 此 ， 我 们 得 
到 了 一 个 空 的 解决 方案 ， 而 且 已 经 配置 好 ， 可 以 编写 代码 了 。 如 果 想 启动 调试 功能 ， 进 入 
“Debug 一 Start Debugging” 菜 单 ， 或 者 按 F5 键 。Visual Studio 会 在 调试 器 中 启动 服务 器 ， 















































注 1: 这 个 .vsix 文件 不 支持 新 版 Visual Studio， 如 果 安 装 出 错 ， 可 以 从 这 里 下 载 : https://github.com/ 
nerobianchi/visual_studio_gallery。 一 一 译 者 注 
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在 正中 打开 http:Wlocalhost:12008/ (端口 可 能 不 同 )， 显 示 Nancy 默认 的 “404 Not Found” 





页 面 。 











2. Xamarin Studio 
写作 本 书 时 ， 在 OS X 和 Linux 中 最 简单 的 搭建 方法 是 ,访问 http://www.monodevelop. 
com/， 下 载 和 安装 MonoDevelop。Mono 是 微软 CLR 规范 的 开源 实现 ，MonoDevelop 是 








与 Visual 


Windows 








Studio 类 似 的 开发 环境 ， 不 过 是 使 用 Mono 构建 的 ， 而 且 完 全 开源 。 如 果 在 
或 OS X 设备 中 安装 MonoDevelop， 它 会 提醒 你 改 为 安装 Xamarin Studio。 这 是 





MonoDevelop 的 新 版 ， 功 能 更 多 ， 也 能 正常 运行 本 章 的 示例 。 


因为 这 两 个 IDE 无 需 安装 针对 Nancy 的 项 目 模板 ， 所 以 直接 新 建 一 个 空 Web 项 目 即 可 。 
进入 “File 一 New 一 Solution” 菜 单 ， 在 模板 选择 对 话 框 中 选择 “ASP.NET 一 Empty ASP. 


NET Proj 





ect”， 如 图 5-3 所 示 。 








Oe New Project 


Choose a template for your new project 


© cross-platform General 


App | 
Empty ASP.NET MVC Project 
Library L_ | 
Tests Empty ASP.NET Project 
© Android [a ASP.NET MVC Project 


App 
Library 


Miscellaneous 





[a ASP.NET MVC Project with Unit Tests 


出 | ASP.NET MVC Razor Project Empty ASP.NET Project 


Creates an empty ASP.NET Web 
ASP.NET MVC Razor Project with Unit Tests Application project. 
20 








| a ASP.NET Project 


Previous | Next | 








5-3: 在 Xamarin Studio 中 创建 一 个 空 ASP.NET 项 目 


这 个 向 导 接 下 来 的 步骤 用 于 设置 项 目 名 称 和 路 径 ， 根 据 需求 填写 即 可 。 


接 下 来 ， 


中 ， 按 但 





更 新 目标 框架 设置 。 在 项 目 (不 是 解决 方案 ) 对 应 的 解决 方案 资源 管理 器 
E Control 键 点 击 或 者 右键 点 击 市 点 ， 从 弹出 的 菜单 中 选择 Options (选项 )。 在 








“Build 一 General” 选 项 卡 中 ， 把 Target Framework 设 为 “Mono / .NET 4.5”( 或 以 上 版 





A 


-A 
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本 )， 然 后 点 击 OK。 


最 后 ， 使 用 NuGet 安装 Nancy 和 Octokit 两 个 包 。 进 入 “Project 一 Add NuGet Packages” 
菜单 ， 打 开 包 管理 器 。 搜 索 Nancy， 勾 选 旁边 的 选择 框 ， 再 搜索 Octokit， 勾 选 旁 边 的 选 
择 框 ， 然 后 点 击 右 下 部 的 “Add Packages”。 安 装 好 之 后 ， 本 章 示 例 代码 所 需 的 环境 就 搭 
建 好 了 。 如 果 想 启动 调试 器 ， 进 入 “Run 一 Start Debugging” 菜 单 ， 或 者 按 四 -Enter 键 。 
Xamarin Se 并 在 浏览 器 中 打开 http://127.0.0.1:80080 (端口 可 能 不 同 )， 现 在 
浏览 器 显示 默认 的 “404 Not Found” 页 下 
































o 


5.2.3 发 送 请 
好 了 ， 项 目 创建 好 了 ， 该 编写 代码 了 。 下 面 我 们 要 让 Nancy 应 用 运行 起 来 。 作 为 优秀 的 工 
程 师 ， 我 们 要 先 编写 测试 。 为 此 ， 要 为 现 有 的 应 用 项 目 生成 一 个 单元 测试 项 目 ， 然 后 添加 
一 个 NuGet 引用 ， 指 向 Nancy.Testing 包 。 此 后 ， 你 可 以 复制 测试 示例 ， 粘 贴 到 模板 生成 
的 默认 测试 模块 顶部 。 


我 们 将 首先 编写 通过 一 个 端点 获取 用 户 粉 丝 数量 的 代码 。 为 了 对 此 进行 测试 ， 我 们 选择 一 
个 有 名 的 用 户 ， 确 认 能 获取 他 的 真名 。 测 试 代码 如 下 。 











using NUnit.Framework; 

using Nancy; 

using Nancy.Testing; 

using Nancy.Bootstrapper; 

using System.Collections.Generic; 
using Nancy.Session; 


namespace NancyApplicationi.Tests 


[TestFixture ()] 
public class Test 


private Browser browser; 


[SetUp] 
public void Setup(){ 
this.bootstrapper = 
new ConfigurableBootstrapper(with => { 
with.Module<Handler>(); 
]); 
this.browser = new Browser (bootstrapper); 


3 


[Test ()] 
public void FetchesUserDetails () 


var result = this.browser.Get ("/mojombo", © 
with => with.HttpRequest ()); 
Assert.AreEquaL (HttpStatusCode.0K, result.StatusCode); 
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Assert.IsTrue (result.Body.AsString() 
.Contains("Tom Preston-Werner")); © 
} 
} 
} 


@ 这 里 使 用 Nancy.Testing 包 提 供 的 Browser 类 向 /mojombo 发 起 请 求 ， 得 到 的 响应 应 该 是 
该 用 户 的 粉丝 数 。 
@ 这 里 断言 从 端点 中 获得 了 mojombo 的 真名 。 








失败 的 测试 有 了 ， 下 面 编写 代码 ， 使 用 Nancy 实现 该 端点 。 这 部 分 代码 的 初始 版 本 如 下 。 


using Nancy 

using Octokit; 

using System; 

using System.Collections.Generic; 
using System.Linq; 


namespace NancyApp 


€ 
public class Handler : NancyModule © 
上 
private readonly GitHubClient client = 
new GitHubClient(new ProductHeaderValue("MyHello")); @ 
public Handler() 
Get["/{user}", true] = async (parms, ct) => © 
var User = await client.User.Get(parms.user.ToString()); @ 
return String.Format("{0} people love {1}!", 
user.Followers, user.Name); © 
}; 
} 
了 
} 


@ 定义 NancyModule 类 的 子 类 ， 在 Nancy 中 接收 和 处 理 HTTP 请 求 具 需 这 样 做 即 可 。 

@ GitHubClient 类 是 Octokit 的 入 口 点 。 我 们 创建 一 个 实例 留待 后 用 ， 这 里 把 产品 名 设 为 
一 个 占 位 符 ， 我 们 访问 的 这 个 API 用 不 到 这 个 名 称 。 

@ 这 个 模块 的 构造 方法 要 求 提 供 路 由 映射 。 我 们 使 用 NancyModule 中 的 Get 字典 把 / 
{user} 映射 到 一 个 匿名 函数 上 上。 索引 运算 符 的 第 二 个 参数 表明 处 理 函 数 是 异步 的 。 

@ 这 一 行 展 示 如 何 从 请 求 URL 中 获取 {user} 部 分 (是 parms 参数 的 一 个 属性 ) ， 以 及 如 
何 使 用 Octokit 查询 GitHub User API。 注 意 ， 要 使 用 await 等 待 网 络 查询 返回 结果 ， 因 
为 查询 可 能 要 花 点 时 间 。 

@ Nancy 处 理 请 求 的 函数 可 以 直接 返回 文本 字符 串 ， 浏 览 器 会 把 这 个 字符 串 视 为 HTML 
代码 。 这 里 ， 我 们 返回 一 个 简单 的 字符 串 ， 包 含 用 户 名 和 粉丝 数 。 
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特别 留意 async 和 await 关键 字 。 这 两 个 关键 字 构成 一 种 特殊 的 句法 ， 把 在 
一 个 事件 循环 中 运行 的 一 系列 函数 封装 起 来 。 看 起 来 这 些 代 码 是 依 序 运 行 
的 ， 但 是 遇 到 await 关键 字 时 ， 系 统 会 发 起 异步 请 求 ， 然 后 把 控制 权 交还 
主事 件 循 环 。 请 求 结束 后 ， 即 实现 承诺 后 ， 事 件 循环 会 回 到 期 待 这 个 await 
关键 字 的 返回 值 那 里 ， 此 时 作用 域 中 的 所 有 变量 都 完好 无 损 。 这 个 功能 
在 .NET 4.0 (2012 年 发 布 ) 中 引入 ， 能 以 几乎 与 同步 代码 一 样 的 方式 编写 异 
步 代 码 。 这 是 众多 开发 者 青睐 C# 的 原因 之 一 。 















































与 “hello, world” 相 比 ， 这 个 示例 有 些 复杂 ， 不 过 还 算 简 洁 明 了 。 这 是 个 好 的 开头 ， 下 面 
实现 OAuth 验证 时 还 要 复杂 一 些 。 


5.2.4 OAuth 验 证 流程 

更 新 提交 状态 之 前 ， 要 获得 用 户 的 授权 。 除 了 询问 用 户 的 用 户 名 和 密码 之 外 (这 种 方式 获 
得 的 权限 太 大 ， 如 果 启 用 了 双重 身份 验证 ， 权 限 还 不 够 用 ) ， 只 能 使 用 OAuth， 而 这 种 验 
证 方式 并 不 那么 简单 。 





下 面 以 这 个 简单 的 服务 器 为 例 概述 OAuth 验证 流程 。 

















(1) 如 果 没 有 授权 令 牌 ， 或 者 令 牌 已 过 期 ， 要 请 求 授 权 令 牌 。 令 牌 就 是 一 个 字符 串 ， 不 过 
不 能 由 我 们 自己 生成 ， 而 要 向 GitHub 索要 。 方 法 是 ， 重 定向 用 户 的 浏览 器 ， 转 到 一 个 
GitHub API 端点 ， 在 查询 参数 中 发 送 所 需 的 权限 类 型 和 其 他 细 市 。 

(2) GitHub (在 浏览 器 中 ) 告知 用 户 有 应 用 在 请 求 权 限 ， 用 户 可 以 同意 ， 也 可 以 拒绝 。 

(3) 如 果 用 户 同意 授权 ， 浏 览 器 会 重 定向 到 第 一 步 指定 的 URL， 并 在 查询 参数 中 传送 一 个 
“代码 ”。 这 不 是 我 们 所 需 的 访问 令 牌 ,而 是 获得 令 牌 的 时 限 密 钥 。 

(4) 在 处 理 请 求 的 函数 中 ， 可 以 使 用 一 个 REST API 获取 真正 的 OAuth 访问 令 牌 ， 然 后 将 其 
存储 在 安全 的 地 方 。 之 所 以 这 么 做 是 因为 ， 如 果 有 令 牌 就 可 以 跳 过 前 面 几 步 。 

(5) 现在 有 权限 了 ， 可 以 在 已 验证 模式 中 使 用 GitHub API。 


过 程 看 起 来 有 点 复杂 ， 不 过 这 样 设计 有 几 个 好 处 。 首 先 ， 可 以 按 作用 域 划分 权限 ， 很 少 有 
应 用 需要 访问 用 户 的 账户 和 数据 的 全 部 权限 。 其 次 ， 整 个 交互 过 程 是 安全 的 ， 至 少 其 中 有 
一 步 要 用 户 手 动 操作 ， 无 法 自动 完成 。 最 后 ， 访 问 令 牌 绝 不 会 传 到 用 户 的 浏览 器 中 ， 这 样 
规避 了 一 整 类 安全 漏洞 。 


















































下 面 分 析 我 们 这 个 简单 服务 器 实现 OAuth 验证 流程 的 代码 。 首 先 ， 如 果 已 经 获得 令 牌 ， 我 
们 把 它 存储 起 来 ， 这 样 每 次 请 求 时 就 不 用 走 一 遍 整 个 重 定向 循环 了 。 我 们 会 把 令 牌 存在 
cookie 中 (此 时 令 牌 会 在 用 户 的 浏览 器 中 传 来 传 去 ， 在 生产 环境 中 ， 应 用 或 许 会 把 令 牌 存 
和 数据 库 )。Nancy 能 帮助 我 们 完成 这 项 操作 ， 不 过 在 此 之 前 要 启用 Nancy， 而 启用 的 方法 
是 使 用 启动 加 载 器 (bootstrapper)。 在 应 用 中 添加 下 面 这 个 类 : 
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using Nancy; 

using Nancy.Bootstrapper; 
using Nancy.Session; 
using Nancy.TinyIoc; 


namespace NancyApp 


} 


Nancy 全 


public class Bootstrapper : DefauLtNancyBootstrapper 
E 

protected override void ApplicationStartup(TinyIloCContainer container, 

IPipelines pipelines) 
{ 
CookieBasedSessions.Enable(pipelines); 

} 

} 





自动 检测 到 启动 加 载 嚣 类， 然后 使 用 它 初 始 化 服务 器 。 现 在 ， 在 NancyModule 中 


可 以 使 用 Session 属性 存 取 cookie 中 的 值 。 


接 下 来 ， 
是 ; 在 














因为 某 些 请 求 要 使 用 应 用 的 ID 和 密令 ， 所 以 要 把 这 两 个 值 写 入 代码 。 方 法 
Handler a 段 。 如 果 没 有 应 用 ， 访问 https://github.com/settings/ 











developers 创建 一 个 ， 把 回调 URL 设 为 http://LocaLhost:8080/authorize (在 不 同 的 环境 
中 ， ee 稍 后 解释 为 什么 这 么 做 。 

















private const string clientId = "<clientId>"; 
private const string clientSecret = "<clientSecret>"; 

















显然 ， 如 果 你 一 直 跟 着 做 ， 那 么 你 应 该 使 用 自己 的 API 应 用 的 ID 和 密令 。 








接 下 来 需要 一 个 辅助 方法 ， 让 它 启 动 OAuth 验证 流程 。 
private Response RedirectToOAuth() 
k 
var csrf = Guid.NewGuid().ToString(); 
Session["CSRF:State"] = csrf; © 
Session[ "OrigUrl"] = this.Request.Path; @ 
var request = new OauthLoginRequest(clientId) 
{ 
Scopes = { "repo:status" }, © 
State = csrf, 
}; 
var oauthLoginUrl = client.O0auth.GetGitHubLoginUrl(request); 
return Response.AsRedirect(oauthLoginUrl.ToString()); @ 
} 
@ CSRF 是 跨 站 请 求 伪 造 (cross-site request forgery) 的 简称 。 这 个 机 制 能 确保 OAuth 请 


求 确 实 是 由 我 们 的 网 站 发 出 的 。 用 户 授权 访问 后 ，GitHub OAuth API 会 传 回 这 个 值 ， 

















我 们 把 它 存 入 cookie， 以 备 后 用 。 























@ 把 源 URL 存 入 会话 cookie 是 基于 用 户 体 验方 面 的 考虑 ， 因 为 OAuth 验证 流程 结束 后 ， 
我 们 想 把 用 户 带 回 他 们 一 开始 想 执行 操作 的 页 面 。 

@ repo:status 是 我 们 请 求 的 权限 。 注 意 ， 这 个 对 象 中 还 包括 CSRF 令 牌 ， 这 样 GitHub 才 
会 把 它 传 回 给 我 们 ， 用 于 后 面 的 验证 。 

@ 这 里 使 用 Octokit 生成 重 定向 URL， 然 后 把 用 户 的 浏览 器 转 到 该 地 址 。 






























































如 果 发 现 令 牌 缺 失 或 无 效 ， 那 么 这 个 模块 中 的 任何 一 个 路 由 处 理 函 数 都 能 调用 
RedirectTo0Auth 方法 。 稍 后 会 说 明 如 何 调 用 ， 现 在 先 继续 处 理 OAuth 验证 流程 。 








在 GitHub 中 设置 应 用 时 ， 我 们 指定 了 一 个 授权 回调 URL。 这 里 ， 我 们 指定 的 是 http:// 
localhost:8080/authorize。 如 果 GitHub 决定 向 应 用 授权 所 请 求 的 权限 ， 它 会 把 用 户 的 浏 
览 器 重 定向 到 该 URL。 那 个 端点 的 处 理 函 数 如 下 ， 这 有 段 代码 要 写 入 模块 的 构造 方法 中 。 























Get["/authorize", true] = async (parms, ct) => © 
{ 
var csrf = Session["CSRF:State"] as string; 
Session.Delete("CSRF:State"); 
if (csrf != Request.Query["state"]) @ 
t 


return HttpStatusCode.Unauthorized; 


} 


var queryCode = Request.Query["code"].ToString(); 

var tokenReq = new OauthTokenRequest(clientId, © 
clientSecret, 
queryCode); 

var token = await client.O0auth.CreateAccessToken(tokenReq); 

Session["accessToken"] = token.AccessToken; @ 


var origUrl = Session["OrigUrl"].ToString(); 
Session.Delete("OrigUr1"); 
return Response.AsRedirect(origUrL); © 

}; 

@ 使 用 Nancy 要 像 这 样 把 路 径 映 射 到 处 理 函数 上 。NancyModule 的 子 类 都 有 一 个 可 索引 对 
象 ， 用 于 处 理 各 个 HTTP 动词 ， 而 且 各 个 动词 都 可 以 依附 同步 或 异步 处 理 函 数 。 此 外 ， 
还 可 以 包含 URL 中 动态 变化 的 部 分 ， 稍 后 会 见 到 一 例 。 

@ 这 行 代码 验证 之 前 生成 的 CSRF 令 牌 。 如 果 不 匹 配 ， 说 明 有 可 疑 的 事情 ， 因 此 返回 401 
响应 码 。 

@ 请 求 REST API， 把 OAuth 代码 转换 成 访问 令 牌 。 为 了 保证 的 确 是 我 们 的 应 用 在 请 求 令 
牌 ， 我 们 传人 了 客户 端 ID 和 密令 ， 以 及 GitHub 提供 给 我 们 的 代码 。 

@ 这 行 代码 把 得 到 的 令 牌 存 入 会话 cookie。 再 次 声明 ， 真 正 的 应 用 不 该 这 么 做 ， 但 是 对 
这 个 示例 应 用 而 言 无 妨 。 

@ 这 行 代 码 把 用 户 重 定向 到 最 初 想 执行 操作 的 页 面 ， 尽 量 不 打 断 原来 要 做 的 事情 。 
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个 端点 可 以 测试 ， 不 过 要 想 办 法 处 理会 话 。 为 此 ， 我 们 把 下 述 代 码 片 段 添加 到 测试 项 
的 命名 空间 中 。 








public static class BootstrapperExtensions 
{ 
public static void WithSession(this IPipelines pipeline, 
IDictionary<string, object> session) 


{ 
pipeline.BeforeRequest.AddItemToEndOfPipeline(ctx => 
t 
ctx.Request.Session = new Session(session); 
return null; 
]); 
} 
} 


这 是 个 扩展 方法 (extension method) ， 作 用 是 为 请 求 提 供 Session 对 象 ， 用 于 处 理 CSRF。 
定义 好 这 个 方法 之 后 ， 在 测试 组 件 类 中 添加 一 个 测试 方法 : 








[Test] 
public void HandlesAuthorization() 
{ 
// CSRF 令 牌 不 匹配 
bootstrapper .WithSession(new Dictionary<string, object> { 
{ "CSRF:State", "sometoken" }, 
]); 
var result = this.browser.Get ("/authorize", (with) => { 
with.HttpRequest(); 
with.Query("state", "someothertoken"); 
DD; 
Assert.AreEquaL (HttpStatusCode.Unauthorized, result.StatusCode); 


// CSRF 令 牌 匹配 
bootstrapper .WithSession(new Dictionary<string, object> { 
{ "CSRF:State", "sometoken" }, 
{ "OrigUrl", "http://success" }, 





}); 

result = this.browser.Get ("/authorize", (with) => { 
with.HttpRequest(); 
with.Query("state", "sometoken"); 


]); 
result.ShouldHaveRedirectedTo ("http://success"); 


} 
第 一 部 分 设置 一 个 不 匹配 的 CSRF 令 牌 。 会 话 中 的 令 牌 是 "sometoken" (在 请 求 API 之 前 
设 定 )， 而 请 求 中 的 令 牌 是 "someothertoken”( 应 该 由 GitHub 发 送 )， 所 以 我 们 断言 状态 


码 是 401。 第 二 部 分 用 的 是 匹配 的 令 牌 ， 所 以 我 们 断言 啊 应 是 重 定向 ， 转 到 会 话 中 存储 的 
URL。 




















做 完 这 些 之 后 ， 我 们 便 得 到 了 令 牌 ， 接 下 来 可 以 愉快 地 继续 前 行 了 。 为 了 触发 OAuth 验证 
流程 ， 处 理 国 数 唯 一 要 做 的 是 ， 在 需要 时 调用 RedirectTo0Auth() 方法 。 验 证 流程 结束 后 ， 








我 们 的 应 用 会 





自动 把 用 户 带 到 之 前 所 在 的 页 面 


5.2.5 ”处理 状态 的 函数 
走 完 上 述 OAuth 认证 流程 之 后 ， 我 们 得 到 了 令 牌 ， 获 得 了 创建 提交 状态 的 权限 。 下 面 把 下 
述 处 理 函 数 添 加 到 那个 Nancy 模块 构造 方法 中 : 


0 














Get["/{user}/{repo}/{sha}/{status}", true] = async (parms, ct) => © 


{ 


Var accessToken = 


Session["accessToken"] as string; 


if (string.IsNullOrEmpty(accessToken)) 
return RedirectToOAuth(); @ 


client.Credential 


CommitState newSt 


try 
{ 


Var NewStatus 


{ 


s = new Credentials(accessToken); 
ate = Enum.Parse(typeof(CommitState), © 


parms.status, 
true); 


= new NewCommitStatus @ 


State = newState, 


Context = 
TargetUrl 
二 


"example-api-app", 
= new Uri(Request.Url.SiteBase), 


await client.Repository.CommitStatus.Create(parms.user, © 


} 
catch (NotFoundEx 


{ 
} 


return HttpSt 


var template = @" 
+ @"api.github.co 
+ @""">this API e 
return String.For 


下 


parms.repo, 
parms.sha, 
newStatus); 


ception) @ 


atusCode.NotFound; 


Done! Go to <a href=""https://" @ 
m/repos/{0}/{1}/commits/{2}/status" 
ndpiont</a>"; 
mat(template, 

parms.user, parms.repo, parms.sha); 


注意 这 个 处 理 国 数 的 请 求 路 径 : 向 localhost:8080/user/repo/<sha>/<status> 发 起 





GET 请 求 ， 新 建 状 态 。 这 档 


便于 在 浏 览 器 中 测试 ， 不 过 Web 爬虫 也 能 在 不 知 不 觉 中 轻 





易 触发 这 个 API。 对 这 个 示例 来 说 ， 可 以 这 么 做 ， 不 过 在 真正 的 应 用 中 或 许 应 该 使 用 


POST 请 求 。 


这 里 用 到 了 OAuth 辅助 方法 。 如 果 会 话 cookie 中 没有 授权 令 牌 ， 重 新 走 一 遍 OAuth 验 
证 流程 。 如 果 Octokit 请 求 API 时 出 现 授 权 异 常 ， 那 么 也 要 走 一 遍 验 证 流程 ， 不 过 这 里 


没有 给 出 相关 的 代码 。 
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@ 这 里 尝试 解析 请 求 URL 中 的 最 后 一 段 ， 将 其 保存 为 Commitstate 枚 举 的 一 个 成 员 。 
Octokit 会 努力 为 所 有 API 维护 类 型 安全 ， 因 此 不 能 直接 使 用 原始 字符 串 。 

@ NewCommitstatus 对 象 封 装 新 建 状 态 时 能 设置 的 所 有 数据 。 这 里 我 们 设置 前 面 解析 得 
到 的 状态 、 用 于 标识 服务 的 唯一 (但 愿 如 此 ) 上 下 文 值 ， 以 及 不 是 很 有 用 的 目标 URL 
(实际 上 应 该 是 解释 如 何 得 出 结果 的 地 址 )。 

@ 这 是 新 建 状态 的 REST 调用 。 这 是 个 异步 方法 (async)， 因 此 在 处 理 结果 之 前 要 等 待 
(await) 结果 。 

@ 这 个 API 可 能 抛 出 很 多 异常 ， 不 过 我 们 要 处 理 的 最 严重 的 一 个 是 NotFoundException， 
对 应 于 HTTP 404 状态 码 。 这 里 ， 我 们 把 代码 转换 回来 ， 以 提升 用 户 体验 。 

@ 如 果 请 求 成 功 ， 那 么 演 染 一 段 HIML， 作 为 处 理 国 数 的 返回 值 。Nancy 默认 把 响应 的 
content -type 设 为 text/html， 因 此 用 户 会 看 到 可 以 点 击 的 链接 。 






















































































到 此 结束 ! 如 果 你 跟着 我 一 起 做 ， 在 自己 的 项 目 中 输入 了 这 些 代码 ， 那 么 现在 可 以 在 调试 
器 中 运行 或 者 在 ASP.NET 服务 器 中 托管 这 个 应 用 ， 然 后 在 浏览 器 中 打开 URL， 为 你 项 目 
中 的 提交 创建 状态 。 








前 面 说 过 ， 不 过 还 是 要 重申 : 这 个 示例 使 用 GET 请 求 是 为 了 便于 测试 ， 真 正 的 服务 应 该 
使 用 POST 请 求 。 











5.3 小结 
即便 没 写 多 少 代码 ， 读 完 这 一 章 也 还 是 能 学 到 不 少 概念 。 


本 章 中 我 们 学 习 了 Commit Status API[， 见 识 了 如 何 通 过 持续 集成 软件 使 用 该 API。 不 过 我 
们 知道 ， 除 此 之 外 Commit Status API 还 有 很 多 用 途 。 我 们 了 解 到 ， 状 态 可 以 读 写 ，API 状 
态 可 以 把 多 个 状态 合并 成 一 个 通过 或 失败 状态 ， 如 果 默 认 的 状态 合并 方式 不 符合 需求 ， 那 
么 我 们 还 可 以 自己 编写 规则 。 我 们 还 了 解 了 拉 取 请 求 中 绿色 对 号 和 红色 错 号 背后 的 机 制 。 
本 章 介 绍 了 OAuth Web 流程 ， 以 及 这 么 设计 的 原因 。GitHub API 的 很 多 功能 都 依赖 


OAuth， 这 是 授信 和 授权 的 正确 方式 。 有 了 OAuth， 我 们 就 可 以 写 出 与 GitHub 交互 的 一 流 
应 用 ， 既 能 运行 在 Web 中 ， 也 能 运行 在 用 户 的 设备 中 。 








本 章 涵 盖 了 一 些 C# 知识 ， 包 括 包 系 统 、 至 少 一 个 IDE、 匿 名 函数 、 对 象 初 始 化 程序 ， 
等 等 。C# 是 一 门 相当 不 错 的 语言 ， 用 过 一 段 时 间 之 后 再 用 其 他 语言 或 许 会 怀念 它 的 某 
些 特性 。 

本 章 介绍 了 .NET 包 管 理 器 NuGet 的 用 法 ， 以 及 这 个 生态 系统 中 的 几 个 包 。 这 个 功能 异常 
强大 ， 很 多 常见 的 需求 都 有 对 应 的 库 ， 此 外 还 有 诸多 实现 不 常见 需求 的 库 ， 因 此 不 管 你 想 
做 什么 ， 基 本 上 都 能 找到 可 以 帮助 你 的 NuGet 包 。 
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本 章 还 介绍 了 Nancy。 使 用 这 个 库 可 以 通过 简洁 的 句法 和 直观 的 对 象 模型 快速 构建 任何 
HTTP 服务 ， 从 REST API 到 基于 HTML 的 界面 不 一 而 足 。 如 果 你 从 未 站 在 Sinatra 的 角 
度 上 观察 世界 ， 那 么 Nancy 可 能 会 稍微 改变 你 对 Web 服务 器 的 看 法 ， 如果 你 曾 这 么 做 过 ， 
那么 读 完 本 章 后 你 将 对 如 何 使 用 符合 习惯 的 方式 实现 这 种 模型 有 新 的 认识 。 

















最 后 ， 本 章 介绍 了 Octokit， 这 个 库 是 对 REST API 的 封装 ， 类 型 安全 ， 而 且 内 建 异步 支持 
和 OAuth 辅助 功能 。 有 了 这 个 库 ， 处 理 GitHub API 特别 简单 直观 ， 就 像 使 用 任何 .NET 库 
一 样 ， 甚 至 可 以 通过 直觉 推 知 用 法 。 








现在 该 重 回 Ruby 的 怀抱 了 。 下 一 章 介绍 Jekyll (GitHub Pages 使 用 的 就 是 它 )， 以 及 如 何 
使 用 它 搭建 博客 。 
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第 6 章 


Ruby 和 Jekyll 








Jekyll 项 目的 描述 说 它 是 一 个 “使 用 Ruby 开发 的 静态 博客 网 站 生成 器 "。Jekyll 的 核心 是 
一 系列 用 于 构建 网 站 的 简单 技术 。 简 单 是 Jekyll 的 一 大 特点 ， 使 用 Jekyll， 我 们 无 需 学 习 
数据 库 后 端 技术 ， 不 用 在 服务 器 中 安装 复杂 的 软件 ， 也 不 用 像 大 多 数 构建 网 站 的 技术 那样 
执行 各 种 操作 。 很 多 著名 的 技术 博客 使 用 的 博客 引擎 都 是 Jekyll。 


与 GitHub 大 量 使 用 的 许多 开源 技术 一 样 ，Jekyl 最 初 是 由 GitHub 的 联合 创始 人 Tom 
Preson Warner 开发 的 ， 此 外 还 有 37 Signals 的 Nick Quaranto， 不 过 现在 Jekyll 项 目 有 几 千 
个 贡献 者 。 不 出 所 料 ，Jekyll 的 优势 不 在 于 最 初 的 开发 者 有 多 么 才智 过 人 ， 也 不 在 于 想法 
有 多 么 出 类 拔 萃 ， 而 在 于 最 初 的 开发 者 营造 了 和 谐 的 社区 氛围 ， 吸 引用 户 参 与 其 中 。 


6.1 学 习 使 用 Jekyll 构 建 博 客 


本 章 探 讨 Jekyll 博客 的 结构 ， 说 明 涉及 的 几 个 主要 技术 。 熟 悉 Jekyll 之 后 ， 我 们 将 使 用 命 
令 行 工具 从 头 开始 创建 一 个 Jekyll 博客 。 然 后 ， 我 们 将 编写 一 个 Ruby 程序 ， 爬 取 博 客 类 
网 站 ， 把 爬 到 的 信息 转换 成 一 个 新 的 Jekyll 博客 。 


6.2 ”Jekyll 是 什么 


Jekyll 把 满足 特定 结构 的 文件 转换 成 HTML， 它 建立 在 两 个 可 靠 的 工具 之 上 。 其 一 ， 
Markdown， 这 是 一 种 标记 语言 ， 阅 读 性 和 表现 力 极 强 。 甚 二，Liquid Markup， 这 是 一 门 
简单 的 编程 语言 ， 为 构建 现代 化 的 网 页 提供 了 足够 的 组 件 ， 如 条 件 判 断 和 循环 ， 而 且 足 够 
安全 ， 能 在 公共 服务 器 中 运行 任何 页 面 。 有 了 这 两 个 技术 的 支持 ， 加 上 对 布局 结构 的 约 
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定 ， 无需 复杂 的 文件 结构 和 技术 ，Jekyll 就 能 构建 特别 复杂 的 网 站 。 


GitHub 把 Jekyll 博客 存储 在 Git 仓库 中 ， 因 此 原生 支持 Jekyll。 如 果 GitHub 把 仓库 视 作 
Jekyll 网 站 ， 推 送 文 件 后 ，GitHub 会 自动 重新 构建 网 站 。Jekyll 是 一 个 开源 生成 器 ， 为 源 
文件 定义 了 特定 的 结构 ， 这 个 结构 对 其 他 工具 而 言 也 易于 理解 和 处 理 。 这 意味 着 ， 我 们 可 
以 自行 构建 工具 ， 与 Jekyll 博客 交互 。Jekyll 这 样 的 开源 工具 加 上 GitHub API 这 样 优秀 的 
API， 得 到 的 是 强大 的 发 布 工具 。 


在 本 地 操作 Jekyll 


若 想 使 用 Jekyll， 需 要 安装 jekyll 这 个 gem。 如 附录 B 所 述 ， 安 装 Ruby gem 的 方法 是 执 
行 下 述 命令 : 



































$ gem install jekyll 


这 样 安装 有 两 个 问题 。 首 先 ， 在 命令 行 中 运行 命令 之 后 ,命令 消失 了 (不 过 私人 的 shell 历 
史 文 件 中 有 )。 其 次 ， 如 果 要 把 网 站 发 布 到 GitHub 中 ， 我 们 得 确保 Jekyll 及 其 依赖 的 版 本 
完全 匹配 ， 并 确保 在 本 地 笔记 本 中 正常 的 网 站 发 布 到 GitHub 中 也 正常 运行 。 如 果 不 考虑 
这 一 点 ， 那 么 你 时 不 时 会 收 到 来 自 GitHub 的 电子 邮件 ， 如 下 所 示 : 














The page build failed with the following error: 
page build failed 
For information on troubleshooting Jekyll see 


https://help.github.com/articles/using-jekyll-with-pages#troubleshooting 
If you have any questions please contact GitHub Support. 





这 两 个 问题 的 解决 方法 相同 。 你 可 能 见 过 其 他 章节 使 用 Gemfile 文件 安装 Ruby 库 。 这 
种 方式 不 在 命令 行 中 使 用 gen 命令 手动 安装 依赖 ， 而 是 把 依赖 放 入 GenfiLe 文件 中 。 这 
样 ， 使 用 仓库 的 其 他 人 只 需 执行 bundle install 命令 就 能 安装 正确 的 依赖 。 此 外 ， 我 们 
不 直接 使 用 jekyll gem， 而 是 使 用 github-pages gem。 这 个 gem 使 用 的 Jekyll 版 本 与 
GitHub 使 用 的 一 致 。 如 果 你 收 到 了 上 述 电 子 邮 件 ， 执 行 bundle update 命令 ， 确 保安 装 
的 依赖 正确 且 同 步 ， 一 般 这 又 会 在 本 地 产生 问题 ， 但 这 时 解决 这 些 问 题 要 快 很 多 ， 执 行 
如 下 代码 即 可 。 








$ printf "gem 'github-pages' >> Gemfile 
$ bundle install 





使 用 Gemfile 文件 创建 和 管理 依赖 是 明智 的 做 法 ， 这 样 能 确保 本 地 使 用 的 Jekyll 与 GitHub 
中 运行 的 版 本 一 致 。 


现在 可 以 创建 Jekyll 博客 了 。 
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6.3 ”使 用 Jekyll 快 速 创 建 博客 
安装 好 所 需 的 工具 之 后 ， 我 们 来 创建 一 个 简单 的 博客 。 执 行 下 述 命令 : 


$ jekyLL new myblog 
$ cd myblog 


jekyLL new 命令 用 于 创建 微型 Jekyll 博客 所 需 的 基本 结构 。 看 一 下 那个 目录 ， 你 会 见 到 组 
成 Jekyll 博客 基本 结构 的 几 个 文件 。 


jekyLL new 命令 创建 了 两 个 CSS 文件 ， 一 个 用 于 装饰 博客 (main.css) ， 另 一 个 用 于 高 亮 和 外 
法 (syntax.css)。 记 住 ， 网 站 完全 在 你 的 掌控 之 下 。main.css 文件 只 是 样板 ， 如 果 不 符合 你 
的 需求 ， 完 全 可 以 将 其 删除 。 如 果 博 客 中 有 代码 片段 ，syntax.css 文件 能 高 亮 句法 ， 美 化 多 
数 编程 语言 。 

新 建 博客 时 还 会 生成 一 个 .gitignore 文件 ， 里 面具 有 一 行内 容 : _site。 使 用 Jekyll 在 本 地 构 
建 网 站 时 ， 默 认 情况 下 所 有 文件 都 会 构建 到 _site 目录 里 。.gitignore 文件 的 作用 是 避免 把 
那些 文件 纳入 仓库 ， 因 为 把 文件 推送 到 GitHub 中 之 后 ， 构 建 网 站 的 Jekyll 命令 会 覆盖 那些 
文件 。 




































































jekyLL new 命令 不 会 创建 并 初始 化 Git 仓库 ， 如 果 想 要 这 么 做 ， 那 就 要 执行 
git init 命令 。 这 个 命令 会 创建 合适 的 结构 ， 便 于 把 所 有 文件 都 添加 到 Git 
仓库 中 。 我 们 只 需 执行 gtt add .; git commit 命令 ，.gitignore 文件 会 被 纳 
入 仓库 ， 并 且 配 置 仓库 忽略 不 需要 的 文件 ， 例 如 _site 目录 。 














所 有 博客 文章 都 存储 在 _posts 目录 里 。 不 是 所 有 Jekyll 网 站 都 有 _posts 目录 (Jekyll 可 用 
于 创建 任何 类 型 的 静态 网 站 )， 但 是 如 果 这 个 目录 中 有 文件 ，Jekyll 会 使 用 特殊 的 方式 处 
理 那 些 文 件 。 现 在 打开 _posts 目录 ， 你 会 看 到 Jekyll 初始 化 命令 创建 的 第 一 篇 文章 ， 文 
件 名 类 似 于 _posts/2014-03-03-welcome-to-jekyll.markdown。 文 章 的 名 称 有 特定 的 格式 : 
先是 日 期 然后 是 文章 标题 (用 连 字 符 取 代 空 格 ) 和 扩展 名 (对 Markdown 文件 来 说 
是 .markdown 或 .md， 对 Textile 文件 来 说 是 .textile)。 














此 外 ， 新 建 的 Jekyll 博客 还 有 几 个 HTML 文件 : index.html 文件 ， 即 博客 的 首页 ， 几 个 
布局 文件 ， 用 于 套 入 生成 的 内 容 。 进 入 _layouts 目录 ， 注 意 里 面 有 个 名 为 defaulthtml 的 
文件 和 名 为 posthtml 的 文件 。 这 两 个 是 布局 文件 ， 用 于 套 入 生成 的 全 部 内 容 ， 例 如 使 用 
Markdown 格式 编写 的 博客 文章 。 比 如 说 ，post.html 文件 用 于 套 入 _posts 目录 中 各 个 文 
件 生 成 的 内 容 。 首 先 ， 把 标记 语言 编写 的 内 容 转换 成 HTML， 然 后 套 入 布局 。 看 一 下 _ 
layouts 目录 中 的 各 个 文件 ， 你 会 发 现 每 个 文件 中 都 有 {{ content ]}} 这样 的 占 位 符 。 这 个 
占 位 符 会 被 替换 成 其 他 文件 生成 的 内 容 。 











其 实 ， 这 些 占 位 符 本 身 也 是 一 种 标记 语言 ， 叫 Liquid Markup， 由 Shopify.com 开发 和 开 
源 。Liquid Markup 之 所 以 出 现 ， 是 因为 人 们 需要 一 种 在 模板 中 幅 入 编程 结构 (如 循环 和 
变量 ) 的 安全 方式 ， 而且 不 能 向 成 熟 的 编程 环境 开放 泻 染 上 下 文 。Shopify 需要 一 种 允许 
不 可 信用 户 在 面向 公众 的 系统 中 上 传动 态 内 容 的 方式 ， 而 且 不 用 担心 标记 语言 放任 恶意 操 
作 。 例 如 ， 如 果 使 用 功能 全 面 的 戏 入 式 编程 语言 ，Shopify 会 面临 被 攻击 的 危险 ， 因 为 用 
户 可 以 编写 代码 连接 内 网 中 的 网 站 。PHP 和 ERB ( 艇 入 式 Ruby 模板 ，Ruby on Rails 框架 
的 用 户 喜 欢 使 用 ) 等 模板 语言 支持 典 入 各 种 代码 片段 ， 这 样 虽然 提供 了 特别 强大 的 功能 ， 
能 完全 控制 源码 文档 ， 但 是 用 户 可 能 会 腊 入 system("rm -rf /") 这 样 的 代码 ， 执 行 危险 操 
作 。Liquid Markup 提供 了 嵌入 式 编 程 模板 的 诸多 优点 ， 同 时 规避 了 和 危险。 本 章 后 面 会 举 几 
个 例子 ， 说 明 如 何 使 用 Liquid Markup。 
































最 后 ，Jekyll 网 站 的 目录 中 有 个 名 为 _config.yml 的 特殊 文件 。 这 是 Jekyll 的 配置 文件 。 打 
开 它 ， 你 会 看 到 几 个 特别 简单 的 设置 ， 





name: Your New JekyLL Site 
markdown: redcarpet 
highlighter: pygments 


这 个 文件 中 只 有 三 行内 容 ， 各 行 的 作用 易于 理解 ， 分 别 设 定 网 站 的 名 称 、Jekyll 命令 使 用 
的 Markdown 解析 程序 和 是 否 使 用 pygments 高 亮 句法 。 
若 想 在 本 地 查看 网 站 ， 执 行 下 述 命 令 : 

$ jekyll serve 


这 个 命令 会 构建 整个 Jekyll 网 站 目录 ， 然 后 启动 一 个 微型 Web 服务 器 ， 伺 服 网 站 。 在 Web 
浏览 器 中 访问 http://localhost:4000， 你 会 看 到 网 站 的 首页 中 显示 了 一 些 内 容 ， 还 列 出 了 一 
篇 博客 文章 ， 如 图 6-1 所 示 。 























Your New Jekyll Site home 


Blog Posts 


03 Mar 2014 » Welcome to Jeky|l! 


Your Name github.com/yourusername 
What You Are twitter.com/yourusername 


you@example.com 











图 6-1: 最 简单 的 Jekyll 网 站 
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点 击 “Blog Posts” 部 分 里 的 链接 ， 你 会 看 到 网 站 中 的 第 一 篇 文章 ， 如 图 





6-2 所 示 。 








Your New Jekyll Site home 


Welcome to Jekyll! 


You find this post in your posts directory - edit this post and re-build (or run with the -w 
switch) to see your changes! To add new posts, simply add a file in the posts directory that 
follows the convention: YYYY-MM-DD-name-of-post.ext. 


Jekyll also offers powerful support for code snippets: 


dof print_hi(nase) 
puts "Hi, #{name)}” 

end 

print hi( Ton') 


Check out the Jekyll docs for more info on how to get the most out of Jekyll File all bugs/feature 
requests at Jekyll's GitHub repo. 


Your Name 


What You Are 





you@example com 








6-2: 一 篇 示例 文章 





这 篇 文章 是 由 Jekyll 初始 化 命令 创建 的 。 这 篇 文章 背后 的 Markdown 文件 在 前 面 介绍 的 _ 
posts 目录 里 : 


layout: post 
title: 


date: 


"Welcome to Jekyll!" 


2014-03-03 12:56:40 
categories: jekyll update 











这 篇 文章 在 _posts 目录 里 ， 你 可 以 编辑 然后 重新 构建 (或 者 执行 serve 命令 时 加 上 -w 开 
关 )， 查 看 改动 的 内 容 。 如 果 想 新 建文 草 ， 那 么 只 需 在 _posts 目录 中 添加 文件 ， 并 且 遵 守 
这 个 命名 约定 : YYYY-MM-DD-name-of-post.ext。 




















Jekyll 还 为 代码 片段 提供 了 强大 的 支持 : 


{% highlight ruby %} 
def print_hi(name) 
puts "Hi, #{name}" 


end 


print_hi('Tom') 
#=> prints 'Hi, Tom' to STDOUT. 
{% endhighlight %} 





Jekyll 的 更 多 功能 说 明 参 见 文 档 (http:Wjekyllrb.com/) 。 如 果 发 现 缺陷 ， 或 者 需要 什么 功能 ， 
那么 在 GitHub 中 Jekyll 的 仓库 里 创建 一 个 工 单 (https:Wgithub.com/mojombo/jekyll) 。 
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太后 


下 


6 章 

















希望 你 也 同意 ， 与 编写 原始 的 HTML 相 比 ， 这 样 创建 网 站 更 直观 、 更 易于 理解 。 简 单 和 易 
于 理解 是 Jekyll 的 主要 优势 之 一 。 源 文件 易于 理解 了 ， 我 们 就 能 专注 于 内 容 本 身 ， 而 不 用 
分 心 去 管 美化 内 容 的 技术 。 下 面 分 析 这 个 文件 ， 探 讨 几 个 重要 的 部 分 。 























6.3.1 YAML 格 式 的 头 部 元 信息 


Jekyll 文件 的 开头 是 YAML 格式 的 头 部 元 信息 (YAML Front Matter，YFM) : 


Layout: post 

title: "Welcome to Jekyll!" 
date: 2014-03-03 12:56:40 
categories: jekyLL update 


YFM 是 一 段 YAML (YAML Ain't Markup Language)， 前 后 都 有 三 个 连 字 符 。YAML 是 
一 种 简单 的 结构 数据 序列 化 语言 ， 许 多 开源 项 目 用 它 代 替 XML， 因 为 很 多 人 觉得 它 比 
XML 易于 阅读 和 编辑 。 这 个 文件 中 的 YFM 展示 了 几 个 配置 选项 : 布局 (layout)、 标 题 
(title)、 日 期 (date) 和 分 类 列表 (categories ) 。 


布局 指 代 _layouts 目录 中 的 某 个 文件 。 如 果 YFM 中 没有 指定 布局 文件 ， 那 么 Jekyll 假设 
你 想 使 用 名 为 default.html 的 文件 套 入 内 容 。 可 以 看 出 ， 我 们 可 以 在 那个 目录 中 添加 布局 文 
件 ， 然 后 在 YFM 中 履 盖 默认 值 。 这 个 文件 指定 的 布局 是 post。 




















标题 用 于 生成 <titte> 标签 ， 此 外 还 可 以 使 用 Liquid Markup 提供 的 双 花 括号 句法 {{ page. 
title }}， 在 模板 中 的 任何 位 置 插入 标题 。 注 意 ，_config.yml 文件 中 的 变量 使 用 site. 命 
名 空间 引用 ， 而 YFM 中 的 变量 使 用 page. 命名 空间 引用 。 这 个 文件 中 的 标题 虽然 与 文件 
名 一 致 (空格 替换 成 了 连 字 符 ) ， 但 是 修改 YFM 中 的 标题 不 会 影响 Jekyll 生成 的 URL。 如 
果 想 修改 URL， 那 就 要 重 命名 文件 本 身 。 这 个 特性 不 错 ， 因 为 我 们 可 以 稍微 修改 标题 ， 而 
不 影响 当前 的 URL。 














这 个 YFM 中 还 有 两 个 变量 : 日 期 和 分 类 。 这 两 个 变量 完全 可 选 ， 奇 怪 的 是 ，Jekyll 初始 
化 命令 生成 的 结构 和 模板 默认 没 用 到 它们 。 这 两 个 变量 为 文章 提供 了 额外 的 信息 ， 不 过 只 
存储 在 Markdown 文件 中 ， 生 成 的 内 容 中 则 没有 体现 。 分 类 列表 经 常用 于 生成 一 个 索引 文 
件 ， 在 里 面 列 出 各 个 分 类 名 下 的 文章 。 如 果 你 以 前 用 过 WordPress， 那 么 你 有 可 能 接触 过 
分 类 。 在 WordPress 中 ， 请 求 分 类 列表 时 会 从 MySQL 数据 库 读 取 数 据 ， 动 态 生 成 分 类 索 
引 ; 而 在 Jekyll 中 ， 分 类 索引 文件 是 静态 生成 的 。 如 果 想 动态 生成 ， 可 以 创建 一 个 JSON 
文件 ， 存 储 分 类 和 名 下 的 文件 ， 然 后 构建 一 个 JavaScript 小 组 件 ， 在 客户 端 请 求 那个 文件 ， 
与 之 交互 。 通 过 模板 ，Jekyll 能 生成 JSON 文件 (或 其 他 任何 格式 )， 而 不 仅仅 局 限于 生成 
HTML 文件 。 


















































YFM 完全 是 可 选 的 。 没 有 YFM 的 文章 或 页 面 ，Jekyll 也 会 将 其 泻 染 到 网 站 中 。 如 果 没 有 
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YFM， 那 么 页 面 会 使 用 变量 的 默认 值 演 染 ， 因 此 为 了 防止 没 指定 布局 ， 至 少 要 确保 默认 的 
布局 能 套 入 所 有 页 面 。 

















YFM 有 个 重要 的 默认 变量 published (是 否 发 布 )。 这 个 变量 的 默认 值 是 true。 也 就 
是 说 ， 在 Jekyll 网 站 仓库 中 创建 一 个 文件 后 ， 如 果 没 有 手动 设置 published， 那 么 该 文件 
默认 会 发 布 。 如 果 设 为 false， 那 就 不 会 发 布 。 在 私有 仓库 中 ， 我 们 可 以 把 这 个 变量 设 为 
false， 从 而 保证 文章 在 完全 写 完 之 前 对 外 不 可 见 。 可 异 ， 协 助 Jekyll 创建 Markdown 文件 
的 工具 都 不 会 在 YFM 中 显 式 设置 published 变量 ， 因 此 ， 如 果 有 不 想 发 布 的 文章 ， 在 提 
交 文 件 之 前 记得 要 确认 一 下 。 

















6.3.2 ”Jekyll 使 用 的 标记 

YFM 下 面 是 Markdown 文件 的 结构 。 最 简单 的 Markdown 文件 只 包含 文本 信息 ， 没 有 任何 
格式 化 符号 。 其 实 ， 如 果 布 局 得 当 ， 即 使 没有 任何 花哨 的 格式 ， 只 用 纯 文 本 内 容 也 能 写 出 
优秀 的 博客 文章 。 

不 过 ,使 用 少量 的 Markdown 句法 也 可 以 为 文章 增光 添彩 。 我 们 注意 到 的 第 一 个 
Markdown 句法 是 反 引 号 ， 这 个 句法 用 于 包围 短小 的 代码 (或 者 类 似 代码 的 信息 ， 如 文件 
名 )。 使 用 得 多 了 ， 你 便 会 发 现 Markdown 蕴含 的 智慧 ，Markdown 提供 的 格式 化 符号 没有 
HTML 标签 那么 繁琐 ， 却 能 实现 同样 的 格式 。 







































































链接 可 以 使 用 [format][Link] 格式 ， 其 中 Link 是 完全 限定 的 URL (如 http://example. 
com) ， 或 者 是 对 页 面 底部 某 个 链接 的 引用 。 这 个 页 面 中 有 两 个 引用 ， 分 别 是 jekyLL-gh 和 
jekyLL， 我们 可 以 在 页 面 中 使 用 [JekyLL's GitHub repo][jekyLL-gh] 这 样 的 句法 引用 那 两 
个 链接 。 使 用 引用 有 个 额外 好 处 ， 即 可 以 使 用 简称 多 次 引用 同一 个 链接 。 


























Markdown 为 各 级 标题 提供 了 简单 的 句法 ， 不 过 那 篇 示例 文章 中 没有 演示 。 添 加 标题 的 方 
法 是 使 用 # 符号 ， 如 有 果 想 使 用 次 级 标题 ， 重 复 输 入 # 符号 即 可 。 这 些 定 界 符 对 应 于 h 标 
签 ， 两 个 # 符号 对 应 <h2> 标签 。 若 想 把 文本 使 用 <h3> 标签 围 起 来 ， 要 使 用 ### Some Text 
这 样 的 句法 。 如 果 觉 得 在 行 尾 写 上 相同 数量 的 井 号 (### Some Text 故 #) 更 具 表现 力 ， 可 
以 这 么 做 ， 但 这 不 是 强制 要 求 。 


Markdown 为 大 多 数 HTML 元 素 提 供 了 简洁 的 名 法， 包括 有 序列 表 、 无 序列 表 、 强 调 ， 等 
等 。 如 果 找 不 到 相应 的 Markdown 句法 ， 还 可 以 直接 在 Markdown 格式 化 符号 旁 腾 入 常规 
的 HTML。 使 用 Markdown 写 东 西 时 最 好 在 手 旁 放 一 份 Markdown 速 查 表 (https://github. 
comy/adam-p/Markdown-here/wiki/Markdown-Cheatsheet) 。Markdown 由 Daring Fireball 公 司 
的 John Gruber 发 明 ， 他 的 网 站 (http://daringfireball.net/) 对 Markdown 的 用 法 和 缘由 做 了 
更 为 深入 的 说 明 。 


















































6.3.3 ”使 用 Jekyll 命 令 
执行 jekyLL --help 命令 会 显示 Jekyll 命令 的 选项 。 我 们 已 经 用 过 jekyLL serve 命令 ， 它 
的 作用 是 构建 文件 ， 写 入 _site 目录 ， 然 后 以 此 为 根 目录 启动 Web 服务器。 如果 使 用 这 个 





命令 构建 Jekyll 网 站 ， 


你 可 能 还 想 学 习 几 个 开关 。 





如 果 经 常 编写 和 调整 页 面 ， 然 后 切换 到 浏览 器 查看 结果 ， 你 会 发 现 -w 开 关 “watch”"， 监 

















视 ) 很 实用 。 指 定 这 个 开关 后 ， 只 要 改动 了 源 文件 ， 整 个 网 站 就 会 自动 重新 构建 。 编 辑 
并 保存 一 个 文章 文件 之 后 ， 那 个 文件 会 自动 重新 构建 。 不 指定 -w 开关 的 话 ， 必 须 先 关闭 
Jekyll 服务 器 ， 然 后 重新 启动 。 











Jekyll 监视 命令 可 以 重新 加 载 所 有 的 HTML 和 标记 文件 ， 但 是 不 能 重新 加 载 
_config.yml 文件 。 如 果 修 改 了 该 文件 ， 需 要 关闭 再 重启 服务 器 。 

















如 果 在 同一 台 笔 记 本 电脑 中 运行 多 个 Jekyll 网 站 ， 第 二 次 执行 jekyll serve 命令 会 失败 ， 
因为 后 一 个 服务 器 不 能 打开 4000 端口 。 此 时 ， 可 以 执行 jekyLL serve --port 4010 命令 ， 





打开 4010 端口 (或 者 





任何 其 他 想 使 用 的 端口 )。 


6.3.4 在 Jekyll 中 设 定 隐私 级 别 

GitHub 中 的 Jekyll 网 站 仓库 可 以 是 公开 的 ， 也 可 以 是 私有 的 。 在 公开 的 仓库 中 ， 可 以 托管 
由 Jekyll 源 文件 生成 的 公开 内 容 ， 而 不 直接 托管 源 文件 本 身 。 记 住 ， 如 前 所 述 ，YFM 中 没 
有 publishing: false 的 文件 一 旦 推动 到 仓库 中 就 公开 了 。 





6.3.5 ”主题 








Jekyll 原生 不 支持 主题 ， 不 过 可 以 轻易 添加 CSS 文件 或 整个 CSS 框架 。 此 外 ， 如 果 你 喜欢 
某 个 Jekyll 博客 的 主题 ， 还 可 以 派生 那个 仓库 。 本 章 后 面 会 说 明 如 何 添 加 自 定义 的 CSS， 

















以 及 将 其 添加 到 何 处 。 

















6.3.6 发布 到 GitHub 中 
创建 好 博客 之 后 ， 可 以 轻易 将 其 发 布 到 GitHub 中 。Jekyll 博客 有 两 种 发 布 方式 : 


。 作为 github.io 的 子 站 
。 放 在 自己 的 域名 名 下 


GitHub 为 个 人 博客 提供 了 托管 功能 ， 放 在 github.io 域名 名 下 。 此 外 ， 稍 微 配置 之 后 还 能 使 
用 自己 的 域名 托管 网 站 。 
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在 GitHub.io 名 下 托管 Jekyll 博 客 

若 想 在 github.io 名 下 托管 个 人 博客 网 站 ，Jekyll 博客 应 该 放 在 Git 仓库 的 master 分 支 
中 ， 而 且 GitHub 仓库 应 该 命名 为 username.github.io。 一 切 设 置 得 当 之 后 ， 为 仓库 添 
加 GitHub 远程 地 址 ， 然 后 推送 文件 即 可 。 如 果 使 用 hub 工具 (与 Git 和 GitHub 交互 的 命 
令 )， 整 个 过 程 只 需 几 个 简单 的 命令 。 记 得 要 根据 自己 的 用 户 名 修改 第 一 行 。 






































起 初 ，hub 工具 使 用 Ruby 编写 ， 因 此 安装 方法 很 简单 ， 执 行 gem install 
hub 命令 即 可 ， 不 过 后 来 用 Go 语言 重 写 了 。Go 语言 的 安装 过 程 复 杂 些 ， 这 
里 不 做 说 明 。 如 果 你 的 OS X 系统 中 有 brew 命令 ， 可 以 执行 brew install 
hub 命令 安装 hub。 在 其 他 平台 中 的 安装 方法 各 异 ， 请 参照 http://github.com/ 
github/hub， 确 定 你 所 用 系统 的 最 佳 安装 方式 。 









































把 Jekyll 博客 托管 到 github.io 名 下 的 方法 是 执行 下 述 几 个 命令 。 


$ export USERNAME=xrd 

$ jekyll new $USERNAME.github.io 

$ cd $USERNAME.github.io 

$ git init 

$ git commit -m "Initial checkin" -a 

$ hub create # 这 里 需要 登录 …… 

$ sleep $((10*60)) && open SUSERNAME .github.io 





倒数 第 二 行 在 GitHub 中 创建 一 个 仓库 ， 名 称 与 本 地 目录 相同 。 最 后 一 行 休眠 10 分 钟 ， 让 
GitHub 配置 你 的 github.io 网 站 ， 然 后 在 浏览 器 中 打开 网 站 。GitHub 首次 配置 网 站 可 能 需 
要 十 分 钟 ， 不 过 后 续 推 送 能 立即 看 到 新 内 容 。 


6.3.7 ”托管 在 自己 的 域名 名 下 


如 果 想 在 自己 的 域名 名 下 托管 博客 ， 要 使 用 仓库 的 gh-pages 分 支 。 ' 此外， 还 要 在 仓库 中 
创建 一 个 CNAME 文件 ， 并 设置 DNS， 把 你 的 域名 指向 GitHub 服务 器 。 























1. gh-page 分 支 
为 了 使 用 gh-pages 分 支 ， 要 在 仓库 中 检 出 并 创建 这 个 分 支 。 





$ git checkout -b gh-pages 

$ rake post title="My next big blog post" 

$ git add _posts 

$ git commit -m "Added my next big blog post" 
$ git push -yu origin gh-pages 





注 1: 作者 所 说 的 有 误 ， 像 6.3.6 节 那 样 放 在 master 分 支 中 也 可 以 自 定 义 域名 。 这 一 章 对 Jekyll 的 说 明 很 多 
都 过 时 了 , 如 果 想 学 习 最 新 的 技术 ,或 者 想 进 一 步 了 解 Jekyll, 可 以 阅读 译 者 写 的 《Jekyll 小 书 》 (http:// 
译 者 注 








www.ituring.com.cn/book/1833)。 
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记 住 ， 一 定 要 使 用 gh-pages 分 支 。 如 果 仓 库 只 用 于 存储 博客 ， 这 一 点 可 能 不 会 忘记 。 添 加 
-u 开关 的 目的 是 让 Git 记 住 每 次 都 推送 到 gh-pages 分 支 。 








2. CNAME 文 件 
CNAME 文件 是 简单 的 文本 文件 ， 里 面 的 内 容 是 域名 。 





$ echo 'mydomain.com' > CNAME 
$ git add CNAME 

$ git commit -m "Added CNAME" 
$ git push 


把 CNAME 文件 推送 到 仓库 中 之 后 ， 可 以 访问 仓库 的 管理 页 面 ， 确 认 GitHub 是 否 正确 地 
把 你 的 域名 和 博客 关联 起 来 。 为 了 快速 打开 管理 页 面 ， 我 们 可 以 使 用 github gem。 这 个 
gem 已 经 没 人 维护 了 ， 不 过 仍 是 个 有 用 的 命令 行 工 具 。 























$ gem install github 
$ github admin # 打开 https://github.com/username/repo/settings 














github gem 是 个 有 用 的 命令 行 工具 ， 可 惜 针对 的 是 旧版 GitHub API， 因 此 文档 中 说 明 的 功 
能 常常 是 错 的 。 


如 果 设 置 正确 ， 在 设置 页 面 的 中 部 会 看 到 如 图 6-3 所 示 的 内 容 。 

















GitHub Pages 


Your site is published at http-/blog.teddyhyde.com 


Update your sito 
To update your site, push your HTML or jekyil updates to your gh-pages branch. More Info 


Overwrite your site by using our automatic page generator. FE 9 本 


Author your content in our markdown editor, select a theme, then publish. 











6-3: Jekyll 博客 的 设置 


GitHub 正确 识别 了 CNAME 文件 ， 因 此 会 在 自己 的 服务 器 中 处 理发 往 那个 域名 的 请 求 。 不 
过 还 没 结束 ， 我 们 要 为 网 站 设置 DNS。 





3. 设置 DNS 

为 网 站 设置 DNS 通常 很 简单 。 如 果 设 置 的 是 子 域 ， ee (apex domain)， 那 
更 简单 。 具 体 而 言 ， 裸 域 是 指 mypersonaldomain.com 这 样 的 域名 ， 子 域 是 指 blog. 
mypersonaldomain.com 这 样 的 域名 。 





为 博客 设置 子 域 的 方法 很 简单 : 在 DNS 中 创建 一 个 CNAME 记录 ， 指 向 username.github. 


lo。 
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裸 域 的 设置 稍微 复杂 一 点 ， 必 须 创 建 DNS A 记录 ， 指 向 全 x 地 址 192.30.252.153 和 
192.30.252.154。 这 是 GitHub 目前 使 用 的 他 地 址 ， 以 后 可 能 会 变 。 因 此 ， 使 用 裸 域 有 一 
定 风 险 。 如 果 GitHub 被 迫 更 换 IP 地 址 (比如 说 遇 到 拒绝 服务 攻击 ) ， 那 么 你 也 要 改 ， 而 且 
要 等 待 DNS 传播 开 来 。 而 使 用 子 域 的 话 ， 如 果 GitHub 更 改 了 耳 地 址 ， 那 么 CNAME 记 
录 能 自动 指向 正确 的 IP 地 址 。? 


6.4 导入 其 他 博客 


把 现 有 的 博客 导入 Jekyll 有 很 多 工具 可 用 。Jekyll 博客 中 的 文件 都 有 约定 的 格式 ， 因 此 我 
们 只 需 获 取 各 部 分 内 容 (文章 本 身 和 相关 的 元 数据 ， 如 文章 标题 、 发 布 日 期 ， 等 等 ) ， 然 
后 将 其 写 入 文件 。Jekyll 推荐 使 用 Markdown 编写 博客 内 容 ， 但 是 也 支持 HIML 格式 的 内 
容 ， 所 以 通 营 毫 不 费力 就 能 转换 博客 ， 此 外 还 有 一 些 优秀 的 工具 能 自动 转换 。 



































6.4.1 导入 WordPress 

最 常 使 用 的 是 导入 WordPress 的 工具 。 为 此 ， 需 要 jekyLL-import gem。 这 个 gem 与 核心 
Jekyll gem 分 开 分 发 ， 不 过 在 Gemfile 文件 中 指定 github-pages gem， 然 后 执行 bundle 命 
令 ， 也 就 安装 了 jekyLL-import。 

1. 直接 从 数据 库 中 导入 

安装 好 jekyLL-import gem 之 后 ， 可 以 使 用 类 似 下 面 的 命令 转换 WordPress 博客 : 


$ ruby -rubygems -e 'require "jekyll-import"; 
JekyLLImport: :Importers::WordPress.run({ 


"dbname" => "wordpress", 
"User" => "hastie", 
"password" => "Lanyon", 

"host" => "LocaLhost'" ， 
"status" => ["publish"] 


})" 


这 个 命令 从 现 有 的 WordPress 中 导入 ， 前 提 是 Ruby 代码 能 访问 数据 库 ， 要 么 能 登录 服务 
器 ， 在 服务 器 中 执行 上 述 命令 ， 要 么 能 通过 网 络 访问 WordPress 博客 的 数据 库 (这 样 托管 
WordPress 不 好 ) 。 











注意 status 选项 ， 这 里 我 们 指定 自动 发 布 导 入 的 页 面 和 文章 。 具 体 而 言 ， 每 个 文件 的 
YFM 中 都 会 指定 published: true， 即 在 Jekyll 博客 中 发 布 页 面 或 文章 。 如 果 想 审阅 各 个 
页 面 和 文章 ， 可 以 把 状态 设 为 private， 这 样 导入 Jekyll 之 后 页 面 处 于 未 发 布 状态 。 注 意 ， 
如 果 仓 库 是 公开 的 ， 标 记 为 未 发 布 的 文章 虽然 不 会 出 现在 博客 中 ， 但 是 可 以 访问 博客 在 
GitHub 中 的 仓库 查看 文章 。 
































注 2: 详情 参见 GitHub 帮助 文档 (https://help.github.com/articles/using-a-custom-domain-with-github-pages/) 。 
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除了 上 面 列 出 的 ， 还 有 很 多 选项 。 例 如 ， 默 认 情 况 下 ，WordPress-Jekyll 导入 工具 会 从 
WordPress 博客 的 数据 库 中 导入 分 类 ， 不 过 我 们 可 以 指定 "categories”=> false 选项 ， 禁 
止 导入 分 类 。 











2. 从 WordPress 博 客 的 XML 文件 中 导入 
另 一 种 导入 方法 是 ， 把 整个 数据 库 导出 为 一 个 XML 文件 ， 然 后 使 用 导入 工具 处 理 该 文件 : 





ruby -rubygems -e 'require "jekyll-import"; 
JekyLLImport::Importers::NordpressDotCom.run({ 
"source" => "wordpress.xml", 
"no_fetch_images" => false, 
"assets folder" => "assets" 


})" 


如 有 果 你 无 权 维护 服务 器 ， 可 以 使 用 这 种 方式 导出 文件 。 不 过 ， 这 种 方法 对 有 权 维 护 的 网 站 
也 能 用 ， 而 且 可 能 比 直接 连接 数据 库 更 好 。 








若 想 导出 XML 文件 ,访问 WordPress 网 站 的 导出 页 面 。 这 个 页 面 的 路 径 通 常 是 /wp-admin/ 
export.php ， 此 网 址 类 似 于 https://blogname.com/wp-admin/export.php (把 “blogname. 
com” 替 换 成 你 博客 的 域名 )。 


与 很 多 免费 工具 一 样 ， 像 这 样 导出 也 有 一 定 的 局 限 性 。 如 果 不 是 简单 的 WordPress 网 站 ， 
使 用 这 个 工具 导入 会 丢失 博客 中 存储 的 众多 元 数据 ， 包 括 页 面 、 标 签 、 自 定义 字段 和 图 像 
附件 。 


如 果 想 保留 元 数据 ， 或 许 应 该 考虑 使 用 其 他 导入 工具 ， 例 如 Exitwp。Exitwp 是 一 个 Python 
工具 ， 把 WordPress 网 站 转换 成 Jekyll 网 站 的 效果 好 得 多 ， 不 过 学 习 曲 线 较 陡 ， 选 项 也 多 。 


6.4.2 ”从 其 他 博客 中 导入 


如 果 使 用 的 博客 程序 不 是 WordPress， 可 能 也 有 对 应 的 Jekyll 导入 工具 。Jekyll 有 许多 导入 
工具 ， 详 情 参见 jekyll-import 网 站 (http://import.jekyllrb.com/)。 









































例如 ， 下 述 示例 命令 摘自 jekyll-import 网 站 ， 作 用 是 导入 Tumblr 博客 : 


$ ruby -rubygems -e 'require "jekyll-import"; 
JekyLLImport: :Importers::TumbLr.run({ 


"url" => "http://myblog.tumblr .com", 
"format" => "html", © 
"grab_images" => false, @ 
"add_highlights" => false, ©@ 
"rewrite urls"” => false ©@ 


}) 
导入 Tumblr 的 插件 有 儿 个 重要 的 选项 。 
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@ 输出 HTML 格式 ， 如 果 想 输出 Markdown 格式 ， 设 为 nd。 

设 为 true 时 ， 抓 取 图 像 。 

日 设 为 true 时 ， 把 代码 块 〈 缩 进 四 个 空格 ) 放 入 “highlight” 这 个 Liquid Markup 标 
签 中 。 


@ 输出 页 面 时 把 Tumblr 博客 中 原来 的 路 径 重 定向 到 Jekyll 博客 中 新 的 路 径 。 








© 





























从 Tumblr 中 导出 比 从 WordPress 中 导出 容易 得 多 。Tumblr 导出 工具 会 疏 取 博客 中 的 全 部 
公开 文章 ， 然 后 将 其 转换 成 兼容 Jekyll 的 文章 格式 。 








我 们 知道 如 何 使 用 import.jekyllrb.com 网 站 提供 的 导入 工具 导入 了 ， 可 是 如 果 需 要 导入 非 
标准 的 网 站 该 怎么 办 呢 ? 


6.5” 拒 取 网 站 ， 导 入 Jekyll 


Jekyll 提供 了 众多 导入 工具 ， 能 轻易 把 现 有 的 博客 导入 Jekyll 博客 。 但 是 ， 如 果 不 是 标准 
的 博客 ， 或 者 不 是 博客 ， 也 有 方法 迁移 到 Jekyll。 第 一 种 方法 是 ， 仔 细 研 究 GitHub 中 的 
Jekyll 导入 工具 源码 (http://github.com/jekyll/jekyll-import)， 自 己 编写 导入 工具 。 如 果 计 
划 把 导入 工具 提供 给 别人 使 用 ， 这 或 许 是 正确 的 做 法 ， 因 为 在 这 个 过 程 中 会 扩展 现 有 的 
Jekyll 导入 类 ， 为 其 他 贡献 者 建立 导入 标准 。 


另 一 种 方法 是 输出 Jekyll 博客 格式 的 文件 。 当 然 ， 这 比 阅 读 Jekyll 导入 工具 及 其 代码 库 轻 
松 得 多 。 一 开始 ， 我 是 一 名 Perl 程序 员 ， 始 终 坚 信 Larry Wall (Perl 之 父 ) 的 一 句 话 :“ 我 
们 鼓励 你 培养 程序 员 的 三 个 良好 品质 : 懒惰 、 没 耐心 和 骄 做 。” 那 我 们 就 顺应 懒惰 之 心 ， 
选择 第 二 种 方法 。 我 们 将 编写 一 些 代 码 ， 疏 取 一 个 网 站 ， 然 后 从 头 新 建 一 个 Jekyll 网 站 。 
在 这 个 过 程 中 ， 通 过 不 断 试 错 学 习 Jekyll 博客 的 结构 。 






























































2000 年 在 巴西 时 ， 我 创建 了 一 个 网 站 ， 名 为 ByTravelers.com， 这 是 我 早期 的 一 个 旅行 博 
客 。 有 一 天 ， 我 不 幸 丢 失 了 数据 库 ， 以 为 网 站 的 内 容 彻底 消失 了 。 一 次 偶然 的 机 会 ， 

在 Archive.org (互联 网 存档 网 站 ) 中 发 现 了 ByTravelers。 那 个 网 站 列 出 了 我 几乎 所 有 的 文 
章 。 真 正 的 数据 库 早已 消失 不 见 ， 通 过 Archive.org 能 恢复 我 的 数据 吗 ? 











6.5.1 ”把 取 策 略 


首先 ， 我 们 要 了 解 Archive.org 提供 的 存档 结构 。 打 开 Archive.org， 在 页 面 中 部 的 搜索 框 中 
输入 “bytravelers.com”， 然 后 点 击 “BROWSE HISTORY”。 你 会 看 到 一 个 日 历 视图 ， 显示 
着 互联 网 存档 网 站 扑 取 我 的 网 站 得 到 的 所 有 页 面 ， 如 图 6-4 所 示 。 
























































INTERNET ARCHIVE 


http://bytravelers.com 
Saved 171 times between May 11, 2000 and May 17, 2014. 
PLEASE DONATE TODAY. Your generosity preserves knowledge for future generations. Thank you. 
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图 6-4: Archive.org 的 日 历 视图 


2003 年 中 ， 我 关 掉 服务 器 ， 准 备 升级 网 站 ， 换 用 其 他 技术 ， 可 是 此 次 迁移 没有 完成 ， 数 
据 都 丢失 了 了。 点击 2003 年 6 月 6 日 ， 我们 会 看 到 那个 网 站 的 功能 和 数据 最 丰富 时 期 的 
页 面 。 虽然 有 儿 个 图 像 无 法 显示 ,但 是 网 站 的 数据 被 Archive.org 网 站 很 好 地 保存 下 来 了 


( 见 图 6-5)。 








CC A https://web.archive.org/web/20030606160946/http://www.bytravelers.com/ 





‘http:/ /www.bytravelers,com/ 
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图 6-5: Archive.org 中 ByTravelers.com 的 存档 
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复制 浏览 器 中 的 URL， 我 们 要 以 此 作为 候 取 的 起 点 。 在 那个 页 面 中 四 处 点 击 ， 我 们 发 现 各 
篇 日 志 的 URL 格式 统一 ， 例 如 http:/www.bytravelers.com/journal/entry/56 表示 网 站 中 存储 
的 第 56 篇 日 志 。 知 道 这 一 点 之 后 ， 我 们 可 以 轻易 迭代 前 100 多 个 URL。 


6.5.2 ”设置 

我 们 将 实现 一 个 简陋 的 肘 虫 ， 座 取 过 程 和 其 他 功能 都 写 在 一 个 Ruby 文件 中 。 不 过 ， 如 果 
把 功能 包装 成 一 个 类 ， 可 以 在 男 一 个 文件 中 实例 化 那个 类 ， 还 可 以 编写 测试 ， 使 用 运行 程 
序 脚 本 验证 仆 取 过 程 。 那 么 ， 我 们 采用 更 好 的 做 法 ， 创 建 三 个 文件 ,分别 用 于 保存 仆 虫 
类 、 运 行程 序 类 〈 实 例 化 并 运行 展 虫 ) 和 测试 代码 (实例 化 并 验证 假 虫 的 功能 )。 


首先 ， 编 写 运 行程 序 脚本 。 
































#!/usr/bin/env ruby 
require './scraper' 


scraper = Scraper.new() 
scraper .run() 


爬虫 类 的 骨架 如 下 所 示 。 

















class Scraper 
def run 


end 
end 


此 外 ， 还 需要 一 个 清单 文件 





Gemfile， 列 出 库 依赖 。 


source "https://rubygems.org" 


gem "github-pages" 
gem "rspec" 


然后 ， 执 行 bundle 命令 安装 gem， 即 安装 rspec 工具 ，Jekyll 工具 及 相关 的 库 。 





最 后 ， 创 建 测 试用 有 具 。 
require './scraper' 


describe "#run" do 
it "should run" do 
scraper = Scraper.new 
scraper .run() 
end 
end 





记 住 ， 要 执行 bundle exec rspec scraper_spec.rb 命令 ,在 这 个 封闭 的 上 下 文中 运行 测试 





(加 载 Gemfile 中 指定 的 库 ， 而 不 是 默认 的 系统 全 局 gem ) 。 


$ bundle exec rspec scraper_spec.rb 


Finished in 0.00125 seconds (files took 0.12399 seconds to load) 
1 example, 0 failures 


现在 还 没什么 可 测试 ， 不 过 测试 用 具 表 明 测 试 代码 与 运行 程序 中 的 代码 紧密 匹配 。 


6.5.3 疏 取 标题 


我 们 从 简单 的 事 入 手 : 从 网 站 中 怜 取 标 题 。 我 们 将 使 用 Ruby 爬 取 网 站 ，Ruby 有 些 直 观 的 
gem， 如 mechanize， 能 简化 构建 Web 客户 端的 过 程 。 0 API， 但 是 我 发 
现 它 很 奇怪 而 且 不 可 靠 ， 因 此 我 们 将 直接 扑 取 网 站 。 执 行 下 述 命令 ， 在 Gemfile 文件 中 添 
加 一 行内 容 ， 然 后 安装 库 。 
































$ echo "gem 'mechanize'" >> Gemfile 
$ bundle 





接 下 来 ， 修 改良 虫 ， 让 它 使 用 mechanize gem 从 Archive.org 中 获取 内 容 。 
require 'mechanize' # @ 
class Scraper 


attr_accessor :root # @ 
attr_accessor :agent 


def initialize # © 
@root = "http://web.archive.org/web/20030820233527/" + 
"http://bytravelers.com/journal/entry/" # @ 
Qagent = Mechanize.new 

end 


def run 
100.times do |i| #©@ 
url = "#{@root}#{i}" # @ 
@agent.get( url ) do |pagel 
puts "#{i} #{page.title}" 
end 
end 
end 


end 


@ 导入 mechanize 库 。 
@ 我 们 使 用 Ruby 方法 attr_accessor 创建 可 公开 访问 的 实例 变量 。 这 个 方法 创建 的 变量 
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可 以 在 变量 名 前 面 加 上 @ 符号 访问 。 实 例 变量 在 类 外 部 也 可 以 访问 。” 

上 日 如 果 类 中 定义 有 initialize 方 法， 创建 对 象 之 后 会 调用 它 。 因 此 ， 这 是 初始 化 成 员 变 
量 的 理想 之 地 。 

@ 初始 化 变量 ， 设 定 默认 值 。 我 们 把 ByTravelers.com 网 站 缓存 副本 的 根 URL 存储 在 这 个 


BR 是 - 
之 时 To。 


@ run 方法 运行 里 面 的 代码 块 100 次 。 
@ 在 这 个 代码 块 中 ， 先 生成 页 面 的 URL， 然 后 获取 页 面 ， 最 后 把 循环 次 数 和 页 面 对 象 的 
标题 打印 出 来 。 


现在 ， 运 行 这 个 聆 虫 ， 看 看 情况 。 





























$ bundle exec ./run.rb 


53 Read Journal Entries 
54 Read Journal Entries 
55 Read Journal Entries 
56 Read Journal Entries 
57 Internet Archive Wayback Machine 
58 Internet Archive Wayback Machine 


我 们 发 现 ， 有 些 条 目的 标题 是 “Internet Archive Wayback Machine”， 有 些 是 “Read Journal 
Entries”。Archive.org 没有 存档 网 站 的 内 容 时 会 返回 占 位 符 (就 像 第 58 个 条 目 那 样 ) 。 我 们 
应 该 忽略 标题 中 不 包括 “Read Journal Entries” 的 页 面 (表明 Archive.org 已 经 缓存 网 站 的 
内 容 )。 


现在 ， 我 们 得 到 了 全 部 内 容 ， 接 下 来 可 以 从 中 寻找 重要 的 部 分 ， 然 后 将 其 放 入 Jekyll 博客 


























6.5.4 借助 交互 式 Ruby 控 制 台 改善 

Mechanize 为 编写 候 取 工具 提供 了 强大 的 基础 ， 有 两 个 原因 : 其 一 ， 便 于 发 送 HTTP 请 求 ; 
其 二 ， 为 搜索 远程 文档 提供 了 强大 的 句法 。 我 们 已 条 见识 到 如 何 使 用 Mechanize 轻松 发 送 
GET 请 求 ， 下 面 探 索 如 何 使 用 它 过 滤 大 量 文档 ， 获 取 重 要 的 文本 内 容 。 我 们 可 以 在 Ruby 
IRB (交互 式 Ruby shell) 中 手动 探索 候 取 过 程 。 
































$ irb -r./scraper 

2.0.0-p481 :001 > scraper = Scraper.new 

=> #<Scraper :OxO0000001e37ca8...> 

2.0.0-p481 :002 > page = scraper.agent.get "#{scraper.root}#{56}" 
=> #<Mechanize: :Page {url #<URI: :HTTP: OxO0000001a85218...> 











注 3: 在 Ruby 中 ， 变量 在 外 部 其 实 并 不 可 以 访问 。attr_accessor 方法 会 创建 实例 变量 ， 同 时 还 会 创建 
存 取 变 0 在 类 外 部 是 通过 存 取 方 法 访问 变量 的 。 一 一 译 者 注 











第 一 行 启动 IRB， 并 使 用 -r 开关 加 载 当 前 目录 中 的 爬虫 库 。 如 果 你 以 前 设 用 过 了 RB， 有 
几 件 事 要 知道 ， 了 解 这 些 事 之 后 ， 你 的 生 话 会 变 得 更 轻松 。 耻 B 中 有 提示 符 ， 指 明 使 用 
的 Ruby 版 本 和 运行 命令 的 序号 。IRB 的 功能 众多 ， 这 里 所 涉 极 少 。 命 令 序 号 可 用 于 重 放 
历史 ， 还 能 用 于 控制 作业 ， 这 与 很 多 其 他 类 型 的 shell 相似 。 在 IRB 提示 符 后 面 可 以 输入 
Ruby 代码 ，IRB 会 立即 执行 ， 然 后 输出 结果 ， 在 => 符号 后 面 打 印 返 回 值 。 在 试验 Ruby 
的 过 程 中 ， 经 常会 遇 到 复杂 的 返回 值 ， 例 如 scraper.agent.get 的 返回 值 是 一 个 Mechanize 
Ruby 对 象 。 这 个 对 象 很 大 ， 打 印 时 要 消耗 大 量 资 源 。 这 里 ， 我 们 简略 了 返回 值 的 大 部 分 
内 容 。 为 了 节省 空间 ， 以 后 讨论 IRB 时 对 许多 复杂 的 对 象 也 会 这 么 做 。 
























































上 述 IRB 中 的 最 后 一 个 命令 把 HTTP GET 请 求 保存 为 一 个 page 对 象 。 获 得 这 个 对 象 之 后 
如 何 从 中 提取 信息 呢 ? Mechanize 提供 了 一 个 精巧 的 语法 糖 (syntactic sugar) ， 搜 索 DOM 
结构 特别 方便 ， 即 “/” 运 算 符 。 我 们 试 试 : 





2.0.0-p481 :003 > page / "tr" 

> pp] 
如 果 查 询 路 径 找 到 了 了 内容， 那么 会 返回 一 个 由 Mechanize 对 象 组 成 的 数组 。 不 过 ， 这 里 得 
到 的 是 空 数组 (表明 什么 都 没 找到 )。 可 异 ， 在 浏览 器 中 加 载 文 档 后 ， 查 询 路 径 会 发 生变 
化 (浏览 器 修改 了 DOM， 或 者 服务 器 为 客户 端 发 送 的 数据 稍微 不 同 )。 但 是 ， 在 IRB 中 测 
试 类 似 的 路 径 能 得 到 所 需 的 内 容 。 我 们 可 以 在 Chrome 和 IRB 之 间 来 回 切 换 ， 在 Chrome 
中 找 出 HTML 的 结构 后 ， 回 到 IRB 中 测试 搜索 路 径 。 最 终 ， 我 们 会 得 出 下 述 搜 索 路 径 。 




















荆 








2.0.0-p481 :004 > items = page / "table[valign=top] tr" 

=> [#<Nokogiri::XML::Element:Oxc05670 name="font" 
attributes=[#<Nokogiri::XML::Attr:Oxc05328 name="size" 
vaLue=" -2">]... 

2.0.0-p481 :005 > items.Length 

5 

2.0.0-p481 :006 > items[0].text() 

=> "\n\n\n\n\n\In\iIn\n\in\nBeautiful Belize\n\n\n\n\n\in\n" 

2.0.0-p481 :005 > items[0].text().strip 

=> "Beautiful Belize" 


就 是 它 了 ， 我 们 找到 了 获取 标题 的 路 径 。 我 们 要 深入 查询 的 结果 ， 不 过 可 以 把 浏览 器 中 页 
面 上 显示 的 文本 与 IRB 中 使 用 查询 找到 的 不 同 结构 对 应 起 来 。 注 意 ， 我 们 要 去 掉 标题 两 侧 
的 空白 ， 这 样 得 到 的 才 是 真正 的 标题 。 我 们 可 以 把 这 些 代码 写 和 人 疏 虫 ， 不 过 现在 最 好 想 想 
如 何 编 写 测试 ， 确 认 这 样 做 是 否 正确 。 编 写 测 试 时 ， 还 可 以 思考 另 一 个 问题 : 缓存 HITP 
请 求 。 








6.5.5 ”编写 测试 ， 处 理 缓存 
再 次 运行 run.rb 脚本 ,会 发 现 它 先 打印 一 个 文档 的 标题 ， 然 后 停 下 来 ， 从 服务 器 中 获取 内 
容 ， 再 打印 一 个 标题 ， 一 直 重 复 ， 直 到 结束 。Archive.org 中 的 内 容 完全 不 会 变 ， 因 为 几 年 
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前 已 经 息 取 了 源 站 ， 内 容 与 儿 个 月 之 前 获取 的 一 样 ， 所 以 没有 新 内 容 要 获取 。 因 此 ， 最 好 
在 爬虫 和 内 容 之 间 放 一 个 缓存 层 ， 减 少 对 Archive.org 的 影响 ， 也 提升 候 取 脚本 的 速度 。 此 
外 ， 可 以 把 获取 内 容 和 处 理 内 容 的 代码 分 开 写 ， 便 于 编写 测试 确认 两 个 过 程 。 























Tl 


require 'mechanize' 
require 'vcr'#@ 
VCR.configure do |c| # 四 


c.cassette_library_dir = "cached ' 
c.hook_into :webmock 
end 


class Scraper 


attr_accessor :root 
attr_accessor :agent 
attr_accessor :pages # © 


def initialize 
@root = "http://web.archive.org/web/20030820233527/" + 
"http://bytravelers.com/journal/entry/" 
Qagent = Mechanize.new 
@pages = []#@ 
end 


def scrape 
100.times do |il| 
begin 
VCR.use cassette("bt #{i}") do # 日 
url = "#{@root}#{i}" 
@agent.get( url ) do |pagel| 
if page.title.eql? "Read Journal Entries" # @ 
pages << page 
end 
end 
end 
rescue Exception => e 
STDERR.puts "Unable to scrape this file (#{i})" 
end 
end 
end 


def process_title( row ) 
row.strip#@ 
end 


def run 
scrape() 
Qpages.each do |page| # © 
rows = ( page / "table[valign=top] tr" ) 
puts process_ title( rows[0].text() ) 
end 
end 





@ 导入 VCR gem。 这 个 gem 会 拦截 HTTP 请求， 正常 放行 首次 请 求 ， 但 是 缓存 后 续 请 
求 ， 整 个 过 程 对 用 户 完全 透明 。 
@ 使 用 VCR 之 前 必须 配置 。 这 里 ， 我 们 指定 把 结果 缓存 在 哪个 目录 里 ， 还 告诉 VCR 使 


用 哪个 模拟 库存 储 缓存 的 结果 。 


























@ 创建 一 个 新 变量 ， 名 为 pages。 我 们 会 把 念 取 到 的 所 有 页 面 存 入 这 个 数组 中 (缓存 信息 





后 将 无 偿 得 至 
@ 初始 化 pages 


I 它们 )。 
数组 。 








@ 为 了 使 用 VCR 的 录制 功能 ， 我 们 把 发 起 HITP 请 求 的 全 部 代码 放 入 一 个 VCR 块 里 ， 





并 为 保存 录制 内 容 的 cassette 指定 一 个 名 称 。 这 里 ， 我 们 使 用 bt ( 指 代 ByTravelers ) 


后 加 页 面 的 序号 来 命名 磁带 。 首 次 使 用 这 个 怜 虫 请 求 页 面 时， 获取 的 内 容 会 存 人 缓存 。 
后 续 调用 抵 虫 的 get 方法 时 ， 会 从 缓存 的 响应 中 获取 内 容 。 


@ 然后 ， 我 们 检查 标题 是 否 像 是 Archive.org 存档 的 页 画 
是 ， 把 页 面 存 入 pages 数组 ， 留 待 后 面 处 理 。 
































i 《使 用 标题 的 内 容 分 辨 )， 如 果 


@ 我 们 把 处 理 标题 的 代码 放 入 专门 的 方法 中 ， 即 process_title 方法 。 这 里 ， 去 掉 传 人 信 


息 中 的 空格 。 





@ 现在 ,在 run 方法 中 调用 scrape 方法 朴 取 页 面 ， 然 后 迭代 各 个 页 面 ， 搜 索 并 处 理 标题 。 








我 们 得 安装 VCR 和 webmock 两 个 库 ， 因 此 要 在 Gemfile 文件 中 添加 这 两 个 gem。 


$ echo "gem 'vcr'" >> Gemfile 
$ echo "gem 'webmock'" >> Gemfile 


$ bundle 


执行 bundle exec ruby ./run.rb 命令 运行 脚本 ,会 看 到 打印 出 了 各 个 标题 。 


$ bundle exec ruby ./run.rb 


Unable to s 
Unable to s 
Unable to s 
Unable to s 
Unable to s 
Unable to s 
Third day i 


crape this 
crape this 
crape this 
crape this 
crape this 
crape this 
n Salvador 


file (14) 
file (43) 
file (47) 
file (71) 
file (94) 
file (96) 


The Hill-Tribes of Northern Thailand 
Passion Play of Oberammergau 


"Angrezis i 


n Bharat" 


Cuba - the good and bad 


Nemaste 


Mexico/Belize/Guatemala 


South Afric 


a 
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我 们 打印 出 了 错误 (表明 Archive.org 没有 存档 那个 URL 对 应 的 页 面 )。 





注意 ， 缓 存 的 副 作 


用 是 脚本 运行 的 速度 快 了 。 如 果 使 用 time 命令 分 析 节 省 的 时 间 ， 可 以 看 到 如 下 结果 。 








$ time bundle exec ruby ./run.rb # 使 用 VCR 之 前 
real Qm29.907s 
user QOm2.220s 
sys gm0.170s 
$ time bundle exec ruby ./run.rb # 使 用 VCR 之 后 
real Qm3.750s 
user QOm3.474s 
sys QOm0.194s 


可 以 看 出 ， 没 用 缓存 之 前 消耗 的 时 间 多 一 个 数量 级 。 而 且 ， 缓存 的 响应 是 无 偿 得 到 的 ， 在 
IRB 会 话 中 也 能 使 用 。 


打印 出 来 的 标题 看 着 不 错 ， 可 是 第 四 个 有 点 不 尽 如 人 意 ， 看 样子 某 个 用 户 把 标题 放 入 双 引 
号 里 了 。 为 了 控制 格式 ， 最 好 把 双 引 号 去 掉 。 下 面 就 来 做 这 一 步 ， 同 时 再 编写 测试 确认 处 
时 方式 是 正确 的 。 




















= 





require './scraper' 


describe "#run" do 
before :each do 
@scraper Scraper .new 
end 


describe "#process_titles" do 
it "should correct titles with double quotes" do 
str = ' something " with a double quote' 
expect( @scraper.process_ title( str ) ).to not match( /"/ ) 
end 


it "should strip whitespace from titles" do 


str = '\n\n something between newlines \n\n’ 
expect( @scraper.process_ title( str ) ).to not match( /^\n\n/ ) 
end 
end 


end 
运行 测试 用 具 ， 我 们 会 发 现 有 一 个 测试 通过 ， 有 一 个 测试 失败 。 


$ bundle exec rspec scraper_spec.rb 
F: 


Failures: 


1) #run #process_titles should correct titles with double quotes 
Failure/Error: expect( @scraper.process_ title( ' something " with 
a double quote' ) ).to not match( /"/ ) 
expected "something \" with a double quote" not to match /"/ 





Di ff : 
QQ -1,2 +1,2 QQ 
Ey 
+"something \" with a double quote" 
# ./scraper_spec.rb:10:in ‘block (3 levels) in <top (required)>' 


Finished in 0.01359 seconds (files took 0.83765 seconds to load) 
2 examples, 1 failure 


Failed examples: 


rspec ./scraper_spec.rb:9 # #run #process_titles should correct titles 
with double quotes 


为 了 让 测试 通过 ， 我 们 要 修改 scraper.rb 文件 中 的 一 行 代码 ， 把 双 引 号 去 掉 。 





def process_title( row ) 
row.strip.gsub( /"/, '' ) 
end 


现在 两 个 测试 都 能 通过 了 。 心 存 戒心 的 程序 员 可 能 会 担心 那 行 代 码 。 如 果 传 入 方法 的 值 是 
nil， 那 么 这 个 方法 会 报错 。 即 便 我 们 可 以 保证 绝对 不 会 出 现 这 种 情况 ， 最 好 也 还 是 让 方 
法 安全 一 些 。 下 面 ， 我 们 要 确保 该 方法 不 会 报错 ， 再 编写 一 个 测试 ， 验 证 确实 如 此 。 


添加 一 个 测试 ， 断 言 process_title 方法 的 参数 为 nil 时 不 会 报错 。 








it "should not crash if the title is nil" do 
expect{ @scraper.process title( nil ) }.to _ not raise error() 
end 


执行 rspec scraper_spec.rb 命令 ， 得 到 如 下 错误 。 这 在 预料 乙 中 ， 因 为 我 们 还 设 修改 
代码 。 


人 ER 
Failures: 


1) #run #process_titles should not crash if the title is nil 
Failure/Error: expect{ @scraper.process title( nil ) }.to not raise error() 
expected no Exception, got #<NoMethodError: undefined method 

‘strip' for nil:NilClass> with backtrace: 
# ./scraper.rb:38:in ‘process_title' 
# ./scraper_spec.rb:20:in ‘block (4 levels) in <top (required)>’ 
# ./scraper_spec.rb:20:in ‘block (3 levels) in <top (required)>’ 

# ./scraper_spec.rb:20:in ‘block (3 levels) in <top (required)>" 





Ruby 和 Jekyll | 107 


Finished in 0.00701 seconds 
5 examples, 1 failure 


Failed examples: 


rspec ./scraper_spec.rb:19 # #run #process_titles should not crash if the title 
# is nil 


六 ! 需 简单 一 改 就 能 侈 正 这 个 问题 





def process_title( row ) 
row.strip.gsub( /"/，'' ) if row 
end 


接 下 来 该 把 文章 写 入 文件 了 。 


6.5.6 ”输出 Jekyll 文 章 

获得 标题 之 后 ， 可 以 生成 实在 的 Jekyll 文章 了 。 简 单 起 见 ， 现 在 只 为 文章 添加 标题 ， 稍 
后 再 添加 其 他 内 容 。 有 了 文章 骨架 ， 我 们 就 能 使 用 Jekyll 命令 行 工 具 测 试 采 用 的 做 法 是 
否 正确 。 






































首先 ， 创建 一 个 Git 仓库 来 存放 文件 。Jekyll 工具 会 转换 所 有 文件 并 写 入 _site 目录 中 ， 因 
此 我 们 要 添加 .gitignore 文件 ， 忽 略 这 个 目录 : 








git init 

mkdir _posts 

echo "_site" >> .gitignore 

git add .gitignore 

git commit -m "Initial checkin" 


LT LT LT LT LT 





Jekyll 文件 特别 简单 ， 开 头 是 一 些 YAML， 后 面 是 使 用 Markdown 编写 的 文本 内 容 。 为 了 
生成 Markdown 格式 文章 ， 我 们 将 在 爬虫 中 添加 一 个 名 为 write 的 方法 ， 从 Archive.org 获 
取 并 解析 页 面 之 后 ， 把 处 理 后 的 信息 写 入 文件 。 





























Jekyll 文章 存储 在 _posts 目录 里 。 按 约定 ， 文 件 名 中 包含 日 期 和 标题 ， 使 用 小 写字 母 ， 而 
且 只 能 有 从 a 到 z 的 英文 字母 和 连 字 符 ， 最 后 是 扩展 名 (Markdown 文件 通常 使 用 .md) 。 
为 了 正确 生成 文件 名 ， 还 要 扑 取 日 期 ， 下 面 就 来 做 这 一 步 。 


举 两 个 实例 。 对 2001 年 1 月 12 日 发布 的 “Cuba 一 the good and bad” 一 文 来 说 ,文件 名 是 
2001-01-12-cuba-the-good-and-bad.md， 人 而 同一 天 发 布 的 “Mexico/Belize/Guatemala” 一 文 
对 应 的 文件 名 是 2001-01-12-mexico-belize-guatemala.md。 为 了 确保 按 约定 行事 ， 我 们 要 
编写 测试 ， 如 下 所 示 。 











describe "#get filename" do 
it "should take 'Cuba - the good and bad' on January 12th, 2001" + 
" and get a proper filename" do 
input = 'Cuba - the good and bad’ 
date = "January 12th, 2001" 
output = "2001-01-12-cuba-the-good-and-bad.md" 
expect( @scraper.get filename( input, date ) ).to eq( output ) 
end 


it "should ‘Mexico/Belize/Guatemala. and get a proper filename" do 
input = "Mexico/Belize/Guatemala" 
date = "2001-01-12" 
output = "2001-01-12-mexico-belize-guatemala.md" 
expect( @scraper.get filename( input, date ) ).to eq( output ) 
end 
end 





下 面 定义 get_filename 方法 。 这 个 方法 使 用 Ruby 中 便利 的 DateTime.parse 方法 把 日 期 的 
字符 串 表示 形式 转换 成 日 期 对 象 ， 然 后 使 用 strfmtime 方法 格式 化 日 期 对 象 ， 得 到 文件 名 
中 所 需 的 格式 。 











def get_fiLename( title, date ) 
processed date = DateTime.parse( date ) 
processed title = title.downcase.gsub( /[^a-z]+/, '-' ) 
"#{processed_date.strftime('%Y-%m-%d' )}-#{processed_title}.md" 
end 


现在 运行 测试 ， 会 看 到 两 个 都 能 通过 。 
接 下 来 ， 在 谎 虫 中 添加 下 述 代码 ， 输 出 文章 。 


def render( processed )#@ 


processed['Layout'] = 'post' 
rendered = "#{processed.to_yaml}---\n\n"#@ 
rendered 

end 


def write( rendered, processed ) # 加 
Dir.mkdir( "_posts" ) unless File.exists?( "_posts" ) 
filename = get filename( processed['title'], processed['creation date'] ) 
File.open( "_posts/#{filename}", "w+" ) do |f| 
f.write rendered 
end 
end 


def process_creation_date( date ) 
tuple = date.split( /last updated on:/ )#@ 
rv = tuple[1].strip if tuple and tupLe.Length > 1 
rv 

end 
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def run 
scrape() 
@pages.each do |page| # © 


rows = ( page / "table[valign=top] tr" ) 


processed = {} 
processed[ 'title'] = process_titLe( 


rows[0].text() ) 


processed[ 'creation date'] = process_creation date( rows[3].text() ) # @ 


rendered = render( processed ) 
write( rendered, processed ) 
end 
end 


@ 定义 render 方法 ,把 输入 的 处 理 后 信息 (一 个 散 列 ) 泻 染 成 正确 的 格式 ， 即 YAML 格 
式 的 头 部 元 信息 (YFM) 和 正文 (现在 没有 )。 返 回 值 是 泻 染 后 的 字符 串 。 

@ 在 散 列 上 调用 to_yaml 方法 。 这 个 方法 由 yaml 库 提 供 ， 导 入 的 方法 是 require “yamlL' 
(这 里 没有 给 出 ， 不 过 能 轻易 添加 到 scraper.rb 文件 中 ，GitHub 中 的 示例 有 ) 。 

@ write 方法 把 演 染 后 的 内 容 写 入 硬盘 。 这 个 方法 首先 检查 有 没有 _posts 目录 ， 如 果 没 
有 ， 那 就 创建 一 个 。 然 后 ， 调 用 get _filenanme 方法 获取 路 径 ， 并 在 前 面 加 上 “_posts”。 











@ process_creation_date 方法 的 参数 是 爬 取 
串 “Last updated on:” 处 把 那 一 部 分 拆 分 

















得 到 的 页 面 中 的 一 部 分 内 容 ， 作 用 是 在 字符 
开 ， 返回 结果 数组 中 的 第 二 个 元 素 。 


@ run 方法 在 前 面 用 过 的 查询 路 径 找到 的 行 里 查找 日 期 和 标题 ， 构 建 processed 散 列 。 
@ 处 理 构建 好 的 processed 散 列 ， 把 泻 染 得 到 的 字符 串 写 入 文件 系统 。 








执行 bundle exec ruby ./run.rb 命令，_posts 目录 中 会 生成 多 篇 文章 。 随 便 选 择 一 个 打 





开 ， 会 看 到 类 似 下 面 的 内 容 : 











title: Beautiful Belize 
creation_date: '2003-03-23' 
layout: post 


可 以 看 出 ， 目 前 文章 中 只 有 YFM， 不 过 这 样 也 完全 是 有 效 的 Jekyll 文章 。 


接 下 来 将 使 用 jekyll 命令 行 工 具 查 看 文章 ， 六 


6.5.7 ”使 用 jekyll 命 令 行 工具 
我 们 可 以 花 点 时 间 把 文件 纳入 Git 仓库 ， 然 后 








F 且 排查 Jekyll 仓库 中 出 现 的 问题 。 


使 用 jekyll 命令 行 工具 查看 网 站 。 在 本 地 使 


用 这 个 命令 行 工具 可 以 查看 新 增 的 内 容 ， 即 时 发 现 错误 (不 用 等 发 布 到 GitHub 之 后 收 到 
邮件 通知 )。 如 果 怜 虫 没有 正确 处 理 从 Archive.org 获取 的 HTML， 或 者 随后 没有 生成 正确 














的 Markdown 内 容 ， 那 么 可 能 会 出 错 。 





$ git add . 
$ git commit -m "Make this into a JekyLL site" 


$ jekyll serve --watch 
Configuration file: none 
Source: /home/xrdawson/bytravelers 
Destination: /home/xrdawson/bytravelers/_site 
Generating... 
Build Warning: Layout 'post' requested in _posts/2000-05-23-third-day-in... 
Build Warning: Layout 'post' requested in _posts/2000-08-28-the-hill-tri... 


done. 
Auto-regeneration: enabled for '/home/xrdawson/bytravelers' 
Configuration file: none 
Server address: http://0.0.0.0:4000/ 
Server running... press ctrl-c to stop. 

















可 以 看 出 ， 现 在 有 几 个 问题 。 基 一， 没有 “post” 布 局， 其 二 ， 没 有 配置 文件 。 下 面 修正 


这 两 个 问题 。 


在 根 目录 中 添加 一 个 名 为 _config.yml 的 文件 。 














name: ByTravelers.com: Online travel information 
markdown: redcarpet 
highlighter: pygments 


记 住 ，jekyll 工具 不 会 自动 重新 加 载 配置 文件 ， 所 以 我 们 要 按 Ctrl-C 键 ， 然 后 重启 。 














接着 ， 新 建 layouts 目录 ， 在 里 面 新 建 post.html 文件 ， 然 后 写 入 下 述 内 容 。 











layout: default 


<h1>{{ page.title }}</h1> 


{{ content }} 


这 个 post.html 布局 文件 特别 简单 ， 使 用 Liquid Markup 标签 显示 文章 的 标题 (使 用 模板 中 
有 权 访 问 的 page 对 象 获取 ) 和 内 容 ( 即 泻 染 文章 得 到 的 输出 )。 


此 外 ， 还 要 创建 “default” 布 局 。 因 此 ， 我 们 要 在 _layouts 目录 中 新 建 一 个 文人 人 
名 为 default.html。 











上 上 





， 将 其 命 


TT 








<htmL> 

<head> 
<title>ByTravelers.com</title> 
</head> 


<body> 





Ruby 和 Jekyll | 111 


{{ content }} 


</body> 

</htmL> 
这 个 文件 的 内 容 几 乎 都 是 HIML， 只 有 一 个 {{ content ] 标签 。 如 果 在 Markdown 文件 
的 YFM 中 把 布局 设 为 default，Markdown 文本 转换 成 HTML 之 后 会 套 入 那个 布局 文件 。 
可 以 看 出 ， 文 章 文件 指定 的 布局 是 post， 这 个 布局 用 于 套 入 文章 内 容 ， 而 post.html 布局 文 
件 指 定 的 布局 是 default.html， 因 此 所 有 内 容 都 会 套 入 default 布局 。 











添加 这 些 文件 之 后 ，Jekyll 命令 行 工 具 会 注意 到 文件 系统 发 生 了 变动 ， 因 此 会 重新 生成 文 
件 。 现 在 ， 我 们 生成 了 文章 ， 但 是 还 没有 主 索引 文件 。 下 面 来 添加 这 个 文件 。 














6.5.8 ”使 用 Liquid Markup 编 写 主 索引 文件 
现在 能 正确 生成 文章 了 ， 但 是 博客 还 没有 和 口 页 面 。 我 们 可 以 创建 一 个 index.md 文件 ， 把 
博客 文章 全 部 列 出 来 。 


Layout: default 


# ByTravelers.com 
Crowd sourced travel information. 
<br/> 


<div> 

{% for post in site.posts %} 

<a href="{{ post.url }}"><h2> {{ post.title }} </h2></a> 
{{ post.content | strip_htmL | truncatewords: 40 }} 
<br/> 

<em>Posted on {{ post.date | date to_string }}</em> 
<br/> 

{% endfor %} 

</div> 


注意 ， 这 个 文件 中 既 有 Markdown (单个 # 和 转换 成 hi 标签 )， 也 有 常规 的 HTML。 如 果 找 
不 到 所 需 的 Markdown 句法 ， 随 时 可 以 在 Markdown 文件 中 混用 常规 的 HTML。 





输出 标签 使 用 两 对 花 括 号 围 住 内 容 (如 {{ site.title }) ， 而 逻辑 标签 使 用 花 括 号 和 百 分 
号 (如 {3% if site.title 闪 )。 你 可 能 猿 到 了 ， 输 出 标签 用 于 在 页 面 中 显示 可 见 内 容 ， 而 
逻辑 标签 执行 某 种 逻辑 操作 ， 比 如 说 条 件 判断 和 循环 。 


上 述 模板 既 用 到 了 输出 标签 ， 又 用 到 了 逻辑 标签 。{% for ... 六 就 是 逻辑 标签 ， 其 作用 
是 迭代 各 篇 文章 。Jekyll 会 处 理 整 个 _posts 目录 ， 把 数据 存 入 site.posts 变量 ， 供 页 面 使 


















































用 。 因 此 ， 我 们 可 以 使 用 for 逻辑 标签 迭代 site.posts。 如 果 使 用 了 { for ... 季 标签 ， 
那么 后 面 要 以 {% endfor 六 标 签 结束 。 该 for 循环 中 有 儿 个 输出 标签 ， 例 如 输出 文章 URL 
的 { post.url 寺 。 我 们 还 用 到 了 过 滤器 ,这 是 用 于 处 理 数据 的 方法 。 其 中 一 个 过 滤器 是 
strip_html， 你 可 能 猪 到 了 ， 它 的 作用 是 去 掉 HTML 标签 ， 得 到 纯 文 本 。 如 果 文 章 内 容 中 
包含 HTML 标签 ， 那 么 一 定 要 使 用 这 个 过 滤器 。 我 们 还 发 现 ， 过 滤器 可 以 “串联 ”: 先 使 

















用 strip_html 过 滤器 处 理 正 文 ， 





如 图 6-6 所 示 。 









































然后 使 用 truncatewords:40 过 滤器 截取 前 40 个 字符 。 


在 浏览 器 中 打开 http:Wlocalhost:4000， 会 看 到 一 个 简单 的 索引 页 面 ， 列 出 几 篇 文章 的 标题 ， 











€ >》 CC | localhost:4000 





ByTravelers.com 


Crowd sourced travel information. 


Beautiful Belize 


Posted on 23 Mar 2003 


Posted on 10 Oct 2002 


Romantic Prague 


Posted on 10 Oct 2002 


Posted on 10 Oct 2002 


A Day in Krakow, Poland 


Posted on 10 Oct 2002 


The Great Wall 


Posted on 06 Jul 2002 





Two Days in St. Petersburg 


A Visit to Montmartre in Paris 








6-6: 一 个 简陋 的 Jekyll 博客 的 索引 页 面 


这 个 索引 页 面 列 出 了 全 部 文章 ， 





下 面 我 们 修改 一 下 ， 只 列 出 最 新 的 10 篇 。 复 制 ndex.md 


文件 ， 把 新 文件 命名 为 archive.md。 然 后 , 把 {% for post in site.posts %} 标签 改 为 { 
for post in site.posts | limit:10 %]}。 








Jekyll 会 为 每 篇 文章 生成 一 个 页 

















看 。 点 击 任何 一 个 链接 都 会 打开 对 应 的 文章 ， 目 前 只 有 标 





题 。 接 下 来 ， 我 们 可 以 让 谎 虫 获取 页 面 中 余下 的 内 容 了 。 
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6.5.9 疏 取 正文 和 作者 


使 用 IRB 查找 作者 和 正文 。 首 先 ， 查 找 作 者 信息 。 


2.0.0-p481 :037 > rows[2].to_s 
=> "<tr>\n<td align=\"center\">\n\n\n\n<font size=\"+1\">author:..." 
2.0.0-p481 :038 > ( rows[2] / "td font" )[0].text() 


=> "author: \n\nMD \n\n\nread more from this author | \nsee maps from this..." 


2.0.0-p481 :039 > author = ( rows[2] / "td font" )[0].text() 


=> "author: \n\nMD \n\n\nread more from this author | \nsee maps from this..." 


2.0.0-p481 :040 > author =~ /author:\s+\n\n([^\s]+)\n\n/ 
=> 0 

2.0.0-p481 :041 > $1 

-> "MD" 





我 们 首先 查看 第 二 行 的 内 容 ， 把 它 转换 成 原始 的 HTML。 我 们 发 现 有 author: 这 个 字符 上 





Hs 


判断 这 可 能 是 注 明 作者 的 地 方 。 这 个 字符 串 嵌 在 font 标签 和 td 标签 里 ， 可 以 使 用 几 个 搜 
索 路 径 把 这 些 额 外 的 信息 去 掉 。 然 后 ， 我 们 使 用 text() 方法 把 HIML 转换 成 文本 ， 然 后 
使 用 正则 表达 式 提取 author: 字符 串 之 后 的 文本 。 如 果 找 到 匹配 正则 表达 式 的 内 容 ， 而 且 
正则 表达 式 中 有 捕获 组 ， 那 么 捕获 的 内 容 会 在 入 全 局 变量 $1 中 。 当 然 ， 获 取 这 个 信息 的 


























方法 不 止 一 种 。 


接着 ,我 们 要 从 疏 取 的 页 面 中 获取 正文 。 添 加 一 个 名 为 process_body 的 方法 ， 并 把 获取 的 


信息 存 入 processed 散 列 。 


def render( processed ) 
processed['layout'] = 'post' 
filtered = processed.reject{ |k,v| k.eql?('body') }#@ 
rendered = "#{filtered.to yaml}---\n\n" +#@ 
"### Written by: #{processed['author']}\n\n" + 
processed[ 'body'] 
rendered 
end 
#® 
def process_body( paragraphs ) 
paragraphs.map { |p| p.text() }.join "\n\n" 
end 


def run 

scrape() 

@pages.each do |pagel 
rows = ( page / "table[valign=top] tr" ) 
processed = {} 
processed[ 'title'] = process title( rows[0].text() ) 
processed[ 'creation date'] = process_creation date( rows[3].text() ) 
processed['body'] = process_body( rows[4] / "p"” )#@ 
author_text = ( rows[2] / "td font" )[0].text() # © 


processed['author'] = $1.strip if author_text =~ /author:\s+\n\n+(.+)\n\n+/ 


rendered = render( processed ) 
write( rendered, processed ) 





end 


end 








@ render 方 法 要 稍微 改 一 下 ， 因 为 文章 的 YFM 中 没 必 要 包含 整个 正文 。 可 以 使 用 reject 
方法 把 正文 过 滤 掉 。 
@ 然后 ， 把 作者 和 正文 添加 到 泻 染 的 输出 后 面 。 



































@ 处 理 正文 的 方式 很 简单 : 把 各 个 段落 转换 成 文本 (使 用 text() 方法 )， 然 后 在 各 段 之 间 




















插入 两 个 换行 。 使 用 两 个 空 行 分 开 后 ，Markdown 会 将 其 格式 化 成 段落 。 

@ 然后 ， 只 需 调用 process_body 方法 ， 并 把 结果 写 入 processed 散 列 。 

日 接 下 来 使 用 上 述 IRB 会 话 中 找到 的 那个 查询 路 径 获 取 作 者 信息 ， 然 后 将 其 存 和 人 
processed 散 列 。render 方法 会 自动 把 作者 名 插入 YFM 中 ， 我 们 再 将 其 插入 文章 中 。 


现在 可 





























以 执行 bundle exec ./run.rb 命令 ， 重 新 创建 文章 文件 。 


6.5.10 ”把 图 像 添加 到 Jekyll 中 
Jekyll 博客 支持 任何 二 进 制 文件 ， 使 用 正确 的 标记 ， 可 以 把 静态 资源 插入 Markdown 文件 


中 。 下 











把 源 站 的 图 像 添 加 到 这 个 Jekyll 博客 中 。 








def process_image( title ) 


img = ( title / "img" ) 
src = img.attr('src').text() 
filename = src.split( "/" ).pop 


output = "assets/images/" 
FileUtils.mkdir_p output unless File.exists? output 
full = File.join( output, filename ) 


if not File.exists? full or not File.size? full 
root = "https://web.archive.org" 
remote = root + src 
# puts "Downloading #{full} from #{remote}" 
‘curl -L #{remote} -o #{full}. 

end 


filename 


end 


此 处 使 用 久负盛名 的 cURL 下 载 图 像 。 我 们 编写 的 代码 只 会 在 首次 请 求 时 下 载 图 像 文 件 。 


此 处 使 











用 -L 开关 让 cURL 跟踪 重 定向 ， 因 为 源 站 的 图 像 显然 已 经 在 浏览 属 内 重 定向 到 其 他 














URL 了 。 


此 处 要 修改 run 方法 ， 调 用 process_image 方法 : 在 其 他 任何 一 个 处 理 方法 调用 后 添加 


processed[ “image'] = process_image( rows[0] )。 
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ByTravelers.com 使 用 的 图 像 是 我 付费 请 画家 画 的 。 如 果 你 使 用 本 章 的 技术 从 
其 他 网 站 谎 取 图 像 或 文本 内 容 ， 一 定 要 遵守 本 地 和 国际 版 权 法 规 。 











然后 ， 修 改 post 布局 ， 插 入 图 像 。 
Lavolt: default 


<h1>{{ page.title }}</h1> 
<img src="/assets/images/{{ page.image }}"> 


{{ content }} 


重新 生成 页 面 ， 我 们 会 看 到 白色 背景 中 并 列 显示 着 有 色 背 景 的 图 像 ， 这 有 点 难看 。 我 们 可 
以 为 整个 网 站 添加 背景 色 ， 下 面 来 修改 网 站 的 CSS。 

















6.5.11 自 定义 样式 (CSS) 


这 里 要 使 用 Bootstrap， 第 9 章 还 会 再 用 一 次 。 除 了 Bootstrap 之 外 ， 我 们 还 会 创建 一 个 
CSS 文件 ， 用 于 定制 颜色 。 











首先 ， 在 主 布局 文件 default.html 中 引用 Bootstrap 和 那个 自 定义 CSS 文件 。 


<htmL> 
<head> 
<title>ByTravelers.com</title> 


<Link href="/assets/css/bootstrap.min.css" rel="stylesheet"> 
<Link href="/assets/css/site.css" rel="stylesheet"> 


</head> 
<body> 
{{ content }} 


</body> 
</htmL> 


然后 ， 把 Bootstrap 的 CSS 文件 下 载 到 相应 的 文件 夹 里 。 


$ mkdir assets/css 

$ curl \ 
https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css \ 
-0 assets/css/bootstrap.min.css 

















Bootstrap 这 样 的 CSS 框架 能 提供 极 大 的 帮助 ， 不 过 我 们 应 该 继续 使 用 源 站 的 颜色 。 在 
assets/css 目录 中 新 建 一 个 文件 ， 将 其 命名 为 site.css。 





body { 
color: #000000; 


background-color: #CCCC99; 
} 


al 
color: #603; 
} 


.jumbotron { 
background-color: #FFFFCC; 
} 








安装 Bootstrap 框架 之 后 ， 可 以 稍微 修改 一 下 default.html 布局 来 美化 网 站 。 很 多 Jekyll 博 
客 的 外 观 都 十 分 朴实 无 华 ， 可 是 我 们 不 能 被 自己 的 想象 所 束缚 。 














<htmL> 
<head> 
<title>ByTravelers.com</title> 
<Link href="/assets/css/bootstrap.min.css" rel="stylesheet"> 
<Link href="/assets/css/site.css" rel="stylesheet"> 
</head> 


<body> 


<div class="container"> 
<div class="jumbotron"> 
<h1>ByTravelers.com</h1> 
Alternative travel information 
</div> 
<div class='row> 
<div class='span12'> 
<div class="container"> 
{{ content }} 
</div> 
</div> 
</div> 
</div> 
</body> 
</htmL> 





[hdl 





重新 加 载 页 面 ， 你 会 发 现 网 站 精美 多 了 ( 见 


/说 








6-7)。 
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C 





| localhost:4000/index.html 





ByTravelers.com 


Alternative travel information 


Beautiful Belize 


This winter | took a holiday cruise which included the port of Belize City, Belize. | had never traveled to Belize so this was the perfect opportunity; with 
the fares rockbottom. My Friend Mary - who incidentially is MS Buffalo.… Posted on 23 Mar 2003 


Two Days in St. Petersburg 


Russia continues to be more restrictive on its tourists than other European countries. In order to enter Russia you must secure a visa from a Russian 
Consulate in the United States, costing $60 each. The visa was waived if you... Posted on 10 Oct 2002 


Romantic Prague 


1had hoped to be able to get to the hotel from the train station using the subway system and my two-year-old memory of the streets of Prague. | 
found the right subway stop, but took a wrong turn on… Posted on 10 Oct 2002 


A Visit to Montmartre in Paris 


When we emerged from the subway and entered the street scene we understood exactly what she had meant. We were in a bustling, working class 
neighborhood filled with a myriad of people of varying nationalities. Obviously a melting pot neighborhood.... Posted on 10 Oct 2002 





6-7: 





沿用 原来 的 颜色 和 图 像 
至 此 ， 我 们 完全 殿 取 了 一 个 旧 网 站 ， 构 建 了 一 个 全 新 的 Jekyll 博客 。 于 是 ， 接 下 来 只 剩 下 


一 件 事 要 做 了 一 一 鼓励 协作 。 有 了 GitHub， 这 一 点 非常 容易 做 到 。 





6.5.12 ”通过 GitHub 的 “派生 ”功能 鼓励 协作 


Jekyll 博客 是 GitHub 中 的 一 个 仓库 ， 这 一 点 使 得 博客 易于 管理 和 跟踪 变化 。 而 且 ， 只 需 
可 以 轻易 为 你 的 博客 作 贡 献 和 修改 内 容 。 你 可 能 见 过 很 
多 托管 在 GitHub 中 的 软件 项 目 主页 上 有 个 “Fork me on GitHub” 横 幅 。 我 们 可 以 鼓励 他 
人 使 用 拉 取 请 求 参与 博客 的 建设 。 最 后 ， 我 们 要 添加 那个 横幅 ， 邀 请 别人 按照 GitHub 的 
方式 为 我 们 的 博客 做 贡献 。 那 些 横幅 最 初 在 GitHub 博客 中 的 一 篇 文章 (https://github.com/ 
blog/273-github-ribbons) 里 发 布 ， 我 们 将 把 那里 给 出 的 代码 几乎 原封 不 动 地 插入 default. 


点 击 一 个 按钮 就 能 派生 仓库 ， 人 们 























html 文件 ， 唯 一 改动 的 是 指向 仓库 的 链接 。 





<body> 


<a href="https://github.com/xrd/bytravelers.com"> 


<img style="position: absoLute; top: 0; right: 0; border: 0;" 
src="https://..." 
alt="Fork me on GitHub" 
data-canonical-src="https://.../forkme_right_gray_6d6d6d.png"></a> 








<div class="container"> 
<div class="jumbotron"> 
<h1>ByTravelers.com</h1> 
Alternative travel information 


现在 ， 任 何人 都 能 派生 我 们 的 仓库 ， 把 他 们 的 文章 添加 到 _posts 目录 里 ， 然 后 发 起 拉 取 请 
求 ， 让 我 们 把 新 文章 添加 到 我 们 的 Jekyll 博客 中 。 


6.5.13 把 博客 发 布 到 GitHub 中 
与 其 他 仓库 一 样 ， 我 们 可 以 使 用 以 前 用 过 的 命令 把 Jekyll 博客 发 布 到 GitHub 中 。 显 然 ， 你 
应 该 根据 实际 情况 更 换 用 户 名 和 博客 名 。 























$ export BLOG_NAME=xrd/bytravelers.com 

$ gem install hub 

$ hub create $BLOG_NAME # 这 里 可 能 需要 登录 

$ sleep $((10*60)) && open http://bytravelers.com 








最 后 ， 别 忘 了 设置 DNS 记录 ， 并 留 出 足够 的 时 间 ， 让 记录 传播 开 来 。 


6.6 小 结 


本 章 详细 探讨 了 Jekyll， 说 明了 Jekyll 博客 的 结构 。Liquid Markup 是 在 Markdown 文件 
中 使 用 编程 结构 的 强大 方式 ， 本 章 说 明了 这 门 模板 语言 的 大 部 分 重要 概念 。 本 章 分 析 了 
Jekyll 博客 的 内 部 结构 ， 解 说 了 复杂 的 YAML 格式 头 部 元 信息 (YFM)， 以 及 如 何 混用 
HTML 和 Markdown 句法 。Jekyll 博客 可 以 使 用 自 定 义 的 CSS， 我 们 学 习 了 如 何 使 用 完整 
的 CSS 框架 (如 Bootstrap) 搭配 网 站 专用 的 小 型 CSS 文件 。 此 外 ， 我 们 构建 了 一 个 仆 虫 
应 用 ， 使 用 它 获 取 了 一 个 完整 的 远程 网 站 ， 然 后 把 它 转 换 成 了 符合 格式 要 求 的 Jekyll 博 
客 。 虽 然 这 个 爬虫 应 用 针对 的 是 特定 的 网 站 ， 不 过 我 们 编写 了 测试 ， 还 使 用 合理 的 方式 分 
离 了 组 件 ， 这 足以 证 明 你 可 以 重用 多 数 代 码 ， 快 速 构建 自己 的 谎 虫 ， 并 把 其 他 网 站 转换 成 
Jekyll 博客 。 









































下 一 章 继续 探讨 Jekyll， 我 们 会 使 用 GitHub API 的 Java 绑 定 构 建 一 个 Android 应 用 ， 通 过 
Git Data API 为 Jekyll 博客 创建 文章 。 
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第 7 章 


Android 和 Git Data AP| 





目前 你 或 许 还 没有 把 手机 当成 开发 者 工具 使 用 ,但 是 不 久 的 将 来 你 很 有 可 能 会 这 么 做 。 当 
下 的 手机 和 平板 电脑 已 经 适合 阅读 代码 ， 然 而 开发 者 在 笔记 本 电脑 中 使 用 的 编辑 器 还 未 移 
植 到 移动 设备 中 。 可 是 ， 我 们 正在 向 这 个 目标 前 进 。EGit 是 为 Java 开发 的 客户 端 库 ， 编 
写 良 好 ， 支 持 读 取 GitHub 中 存储 的 数据 ， 同 时 也 支持 把 数据 写 入 GitHub。 我 们 可 以 使 用 
这 个 库 为 当今 世界 上 最 流行 的 移动 操作 系统 Android 开发 应 用 。 




















本 章 将 使 用 Java EGit 库 开 发 一 个 小 型 Android 应 用 ， 把 文章 发 布 到 GitHub 中 托管 的 博客 。 
我 们 使 用 这 个 博客 应 用 登录 GitHub， 简 单 说 说 当下 的 感受 ， 然 后 应 用 创建 Jekyll 博客 文 
章 ， 再 把 文章 推送 到 GitHub 中 托管 的 博客 里 。 








7.1 搭建 环境 


为 了 构建 这 个 应 用 ， 我 们 要 创建 一 个 Jekyll 博客 ， 并 且 安 装 所 需 的 Android 构建 工具 。 








7.1.1 创建 Jekyll 博 客 

我 们 要 编写 添加 Jekyll 博客 文章 的 应 用 ， 还 要 验证 应 用 的 行为 符合 预期 ， 因 此 我 们 需要 一 
个 博客 ， 这 样 才能 执行 相关 的 命令 。 新 建 Jekyll 博客 有 多 种 方式 ， 其 中 最 简单 的 是 运行 本 
节 说 明 的 一 系列 Ruby 命令 。 如 果 想 进一步 了 解 Jekyll， 请 翻阅 第 6 章 。 创 建 Jekyll 博客 时 
有 几 件 麻烦 事 要 注意 ， 比 如 说 要 正确 设置 主机 名 ， 还 要 使 用 正确 的 Git 分 支 。 不 过 ， 这 里 
不 用 考虑 这 些 ， 我 们 只 需 确 保 仓 库 中 有 Jekyll 博客 的 文件 结构 即 可 。 
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$ echo "source 'https://rubygems.org'" >> Gemfile 
$ echo "gem 'github-pages'" >> Gemfile 

$ echo "gem 'hub'" >> Gemfile 

$ export BLOG_NAME=mytestblog 

$ bundle 

$ jekyll new $BLOG_NAME 

$ cd $BLOG_NAME 

$ hub create 

$ git push -uyu origin master 


上 述 命 令 先 安装 Jekyll 所 需 的 库 (有 一 个 库 用 于 测试 )， 然 后 使 用 Jekyll 命令 行 工具 生成 一 
个 新 博客 ， 最 后 把 文件 推送 到 GitHub 中 。 在 第 四 行 ， 我 们 指定 了 博客 的 名 称 。 这 个 名 称 
可 以 随意 修改 ， 但 是 记得 要 相应 地 修改 测试 。 























述 命令 执行 结束 后 应 该 关闭 终端 窗口 。 本 章 后 面 会 在 全 新 的 目录 中 使 用 其 
命令 ， 最 好 别 在 创建 Jekyll 博客 的 目录 中 执行 那些 命令 。 我 们 已 经 把 文件 
送 到 GitHub 中 了 ， 因 此 可 以 放心 地 把 这 个 目录 里 的 本 地 仓库 删除 。 
































7.1.2 Android 开 发 工具 
如 果 没 有 Android 实体 设备 ， 那 也 不 用 惊慌 。 按 照 本 章 所 述 的 方法 ， 即 使 没有 实体 的 
Android 设备 ， 也 能 在 虚拟 设备 中 做 开发 和 测试 。 


























1. 安装 Java SDK 

Ruby 和 NodeJS 可 以 分 别 使 用 RVM 和 NVM 通过 简单 的 shell 命令 安装 ， 可 惜 Java 没有 
这 样 的 工具 。Oracle 公司 控制 着 Java 语言 和 官方 SDK 的 分 发 ， 而 且 限 制 只 能 通过 java. 
oracle.com 下 载 。Java 可 以 免费 获取 ， 但 是 必须 访问 java.oracle.com， 找 到 符合 需求 的 下 载 
链接 。Android 支持 Java 1.7 及 以 上 版 本 。 





2. 安装 Android Studio 

我 们 将 使 用 Android Studio， 这 是 用 于 开发 Android 应 用 的 Google IDE。 若 想 安装 ， 访 问 
https://developer.android.com/sdk/index.html， 找 到 针对 你 所 用 平台 的 下 载 按钮 (支持 OS X、 
Linux 和 Windows)。Android Studio 集成 了 构建 Android 应 用 所 需 的 全 部 重要 工具 。 


7.2 新建 项 目 


接 下 来 ， 创 建 Android 项 目 。 初 次 打开 Android Studio 时 ， 在 右面 板 中 会 看 到 一 个 选项 邀 
请 你 新 建 项 目 。 点 击 “Start a new Android Studio project” 选 项 ， 此 时 会 打开 一 个 界面 ， 让 
你 配置 新 项 目 。 在 “Application Name” 中 输入 “GhRU”(“GitHub R U?”) ， 在 “Company 
Domain” 中 输入 “example.com”( 也 可 以 使 用 你 自己 的 域名 ， 不 过 要 知道 ， 这 样本 章 所 
用 的 目录 结构 就 会 与 你 的 不 同 )。Android Studio 会 自动 生成 “Package name”， 妈 com. 
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example.ghru, 





然后 ， 需 要 选择 目标 SDK。 选 择 的 目标 SDK 版 本 越 高 ， 可 供 使 用 的 Android API 越 新 ， 
不 过 能 运行 应 用 的 设备 越 少 。 本 章 的 代码 要 兼容 旧版 SDK， 经 过 权衡 ， 我 们 使 用 Android 
4.4 (KitKat) ， 这 样 应 用 在 手机 和 平板 电脑 中 都 能 运行 。 根 据 Android Studio 的 说 明 ， 这 个 
SDK 目前 支持 世界 上 49.5% 的 Android 设备 ， 如 图 7-1 所 示 。 

















©One Create New Project 


网 Target Android Devices 


Select the form factors your app will run on 


Different platforms may require separate SDKs 


Phone and Tablet 
Minimum SDK API 19: Android 4.4 (KitKat) 


Lower APl levels target more devices, but have fewer features available. By targeting API 19 
and later, your app will run on approximately 49.5% of the devices that are active on the 
Coogle Play Store. 


Help me choose 


Wear 
Minimum SDK API 21: Android 5.0 (Lollipop) 
TV 
Minimum SDK APl 21: Android 5.0 (Lollipop) 
Android Auto 
| Glass 
Minimu m SDK MNC: Android M (Preview) 








Cancel | [Previous | 国 | rinish 











图 7-1: 选择 Android SDK 


接 下 来 ，Android Studio 要 求 我 们 选择 活动 (activity)。 选 择 “Blank Activity”， 此 时 会 出 现 
一 个 界面 ， 让 你 定制 活动 。 保 留 “Activity Name”(“MainActivity”) 及 布局 、 标 题 和 菜单 
资源 名 等 相关 文件 的 默认 值 。 最 后 ， 点 击 “Finish” 按 钮 ， 生 成 项 目 。 














设置 好 之 后 ，Android Studio 会 创建 一 个 Gradle 配置 文件 ， 并 生成 应 用 的 结构 。 这 一 步 完 
成 后 ， 我 们 可 以 点 击 左边 纵向 选项 卡 里 的 “Project” 标 签 页 ， 查看 项 目的 文件 树 ， 如 图 7-2 
所 示 。 
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图 7-2， 首次 查看 Android 项 目的 结构 


如 果 你 从 未 见 过 Android 项 目 ， 可 能 对 这 个 界面 不 熟悉 ， 需 要 解释 一 下 。app 目录 里 是 应 
用 代码 和 资源 (布局 文件 、 图 像 和 字符 串 )。app 目录 中 有 几 个 子 目 录 : java 目录 里 面 显然 
是 项 目的 所 有 Java 代码 ， 包 括 应 用 文件 ， 以 及 把 应 用 发 布 到 商店 中 不 包含 在 应 用 中 ， 但 是 
用 于 测试 应 用 的 程序 ，res 目录 里 是 前 面 提 到 的 资源 。Android Studio 在 Gradle Scripts 部 分 
列 出 所 有 构建 文件 ， 但 是 不 根据 目录 结构 分 组 。 你 会 看 到 两 个 build.gradle 文件 ， 第 一 个 通 
常 可 以 忽略 ， 不 过 我 们 将 修改 第 二 个 。 
































现在 ， 可 以 编辑 项 目 了 。 


7.2.1 编辑 Gradle 构 建文 件 


首先 ， 我们 要 在 Gradle 构建 文件 中 指定 依赖 库 。Gradle 是 针对 Java 的 构建 系统 ， 现 已 成 
为 Android 平台 的 官方 构建 系统 。 打 开 app 模块 里 的 build.gradle 文件 (两 个 中 的 第 二 个 )。 





apply plugin: 'com.android.application' // ©@ 
android { 
compileSdkVersion 23 // 加 
buildToolsVersion "23.0.1" 


defaultConfig { 
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applicationId "com.example.ghru" 
minSdkVersion 21 
targetSdkVersion 23 
versionCode 1 
versionName "1.0" 
testInstrumentationRunner 
"android.support. test.runner.AndroidJUnitRunner" // ©®@ 


} 
buildTypes { 
release { 
minifyEnabled false 
proguardFiles getDefaultProguardFile('proguard-android.txt'), 
"proguard-ruLes.pro' 
} 
} 


} 


dependencies { 
compile fileTree(dir: 'libs', include: ['*.jar']) //@ 
compile 'com.android.support:appcompat-v7:23.0.1" 
compile 'org.eclipse.mylyn.github:org.eclipse.egit.github.core:2.1.5' 
compile( 'commons-codec:commons-codec:1.9' ) 
testCompile ‘junit:junit:4.12' // ©@ 
testCompile "com.squareup.okhttp:okhttp:2.5.0' 
androidTestCompile 'com.android.support.test:runner:0.4' // ©@ 
androidTestCompile 'com.android.support.test:rules:0.4" 
androidTestCompile "com.android.support.test.espresso:espresso-core:2.2.1' 





首先 ， 加 载 Android Gradle 插件 。 这 个 插件 用 于 扩展 项 目 ， 支 持 android 块 。 接 下 来 指 
定 这 个 块 。 

然后 ， 配 置 android 块 ， 例 如 目标 版 本 (创建 项 目 时 选择 的 ) 和 具体 的 SDK， 用 于 编 
译 应 用 。 
为 了 运行 UI 测试， 我 们 要 指定 AndroidJUnitRunner 为 测试 运行 程序 。 

Android Studio 自动 在 构建 文件 中 添加 了 一 个 配置 ， 加 载 lib 目录 里 的 所 有 JAR 文件 
(Java 库 )。 我 们 还 要 安装 兼容 旧版 Android 设备 的 支持 库 ， 以 及 用 于 连接 GitHub 的 
EGit 库 (这 是 最 重要 的 )。Apache 基金 会 开发 的 Commons Codec 库 提 供 了 一 些 工具 ， 
用 于 把 内 容 编 码 成 Base64， 这 是 使 用 Git Data API 把 数据 存 入 GitHub 仓库 的 编码 方式 
ee 

然后 ， 安 装 只 用 于 运行 单元 测试 的 库 。 使 用 testCompile 指定 的 库 ， 仅 当代 码 在 本 地 
开发 设备 中 运行 时 才 编 译 。 在 这 个 场景 下 ， 我 们 需要 JUnit 库 和 Square 开发 的 OkHttp 
库 。 后 者 用 于 验证 提交 请 求 确实 到 达 GitHub API 了 。 

最 后 ， 安 装 Espresso 库 和 Google UI 测试 框架 。 三 个 库 的 首 行 安装 前 面 配置 的 测试 运行 
程序 。 我 们 使 用 的 是 androidTestCompile， 因 此 在 测试 模式 中 运行 Android 代码 时 才 会 
编译 这 些 库 。 
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创建 开发 所 需 的 AVD 

使 用 Android Studio 创建 AVD (Android Virtual Device，Android 虚拟 设备 ) 很 简单 。 先 
打开 “Tools” 菜 单 ， 选 择 “Android”， 然 后 选择 “AVD Manager”。 点 击 “Create Virtual 
Device ”按钮 ， 然 后 跟着 向 导 设 置 。 一 般 来 说 ， 我 们 可 以 随意 选择 任何 设置 。Google 制造 
了 一 个 真实 的 设备 ， 名 为 Nexus 5。 这 是 推荐 使 用 的 Android 设备 ， 能 很 好 地 支持 所 有 功 
能 。 如 果 你 不 知道 该 选 哪 个 ， 就 选 这 个 吧 ， 如 图 7-3 所 示 。 





























Ie@e® Virtual Device Configuration 
| Select Hardware 
Choose a device definition 
S 2 [0 Nexus5 
Category Name 了 Size Resolution Density 
NexusS 4.0" 480x800 hdpi 
Tablet Nexus One 3.7" 480x800 hdpi ee . 
Size: normal 
Ratio: notlong 
Wear Nexus 6P 5 1440x2560 560dpi Density: xxhdpi 
1920px 
TV Nexus 6 5.96" 1440x2560 560dpi 
Nexus 5X 5.2" 1080x1920 420dpi 
Nexus 4 768x1280 xhdpi 
Galaxy Nexus 4.65" 720x1280 xhdpi 
Android Wea... 1.65" 280x280 hdpi 
Android Wea... 1.65" 320x320 hdpi 
5.4" FNVGA 5.4" 480x854 mdpi 
New Hardware Profile Import Hardware Profiles (9p) Clone Device... 
Cancel Previous Next Finish 

















图 7-3: 新 建 AVD 





后 ， 启 动 新 建 的 AVD。 启 动 的 过 程 要 花 儿 分 钟 ， 因 为 AVD 要 使 用 软件 模拟 芯片 组 。 有 
别 的 工具 能 加 速 AVD 的 启动 时 间 (Genymotion 是 其 中 一 个 )， 然 而 ， 如 果 不 使 用 自 带 的 
Android 工具 ， 复 杂 度 会 增 大 ， 因 此 我 们 依然 选择 使 用 AVD。 








7.2.2 ”Android 默 认 的 主 活动 


使 用 上 述 方式 新 建 的 Android 应 用 有 个 示例 入 口 ， 用 于 启动 Android 应 用 。 所 有 Android 
应 用 都 有 一 个 名 为 AndroidManifest.xml 的 文件 ， 这 个 文件 用 于 指定 活动 ， 并 列 出 应 用 所 
需 的 权限 。 打 开 app/src/main 目录 里 的 AndroidManifest.xml 文件 ， 添 加 一 行 代码 ， 为 这 
人 (因为 这 个 应 用 要 与 GitHub API 交互 )。 注 意 ， 在 Android 
Studio 中 查看 这 个 文件 时 ， 这 个 IDE 会 从 资源 中 读 取 数据 ， 自 改 字符 串 ， 因 此 你 会 发 现 
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android:label 属性 的 值 是 灰色 的 GahRU， 而 在 XML 文件 中 真正 显示 的 值 如 下 (@string/ 


app_name ) 。 








<manifest xmlns:android="http://schemas.android.com/apk/res/android" 
package="com.example.ghru"> 


<uses-permission android:name="android.permission.INTERNET" /> 


<application android:allowBackup="true" android:1label="@string/app_name" 
android:icon="@mipmap/ic_launcher" android:supportsRtl="true" 
android:theme="@style/AppTheme"> 


<activity android:name="MainActivity" 
android:label="@string/app_name"> 
<intent-filter> 
<action android:name="android.intent.action.MAIN" /> 
<category android:name="android.intent.category.LAUNCHER" /> 
</intent-filter> 
</activity> 


</application> 


</manifest> 





启动 应 用 时 ，Android 操作 系统 会 启动 这 个 活动 ， 然 后 调用 onCreate 函数 。 这 个 函数 则 调 
用 父 类 的 onCreate 函数 ， 然 后 具 现 应 用 的 布局 。 布 局 是 XML 文件 ， 使 用 声明 的 方式 描述 
Android 应 用 的 UI。 








Android Studio 为 我 们 创建 了 一 个 默认 的 布局 (activity_main.xml) ， 不 过 我 们 不 用 ， 而 
是 新 建 一 个 。 为 此 ， 在 layouts 目录 上 按 右键 (在 OS X 中 按 下 Control 键 再 点 击 )， 选 择 
“New”， 然 后 选择 列表 最 顶部 的 “Layout resource fle”(Android Studio 会 根据 点 击 的 上 下 
文 呈现 最 优 候选 项 )。 把 文件 名 设 为 main.xml， 其 他 设置 保留 默认 值 。 


























这 个 应 用 需要 登录 ， 所 以 我 们 至 少 需要 一 个 用 于 输入 用 户 名 的 字段 和 描述 性 标注 ， 一 个 用 
于 输入 密码 的 字段 (和 相应 的 描述 性 标注 )， 一 个 点 击 后 尝试 登录 的 按钮 ， 以 及 一 个 状态 
字段 ， 指 明 登 录 成 功 还 是 失败 。 那 么 ， 下 面 修改 生成 的 main.xml 文件 ， 设 计 用 户 界面 。 为 
了 以 文本 格式 修改 这 个 文件 ， 点 击 main.xml 面板 底部 “Design” 标 签 页 旁边 的 “Text” 标 
签 页 ， 切换 到 文本 视图 。 然 后 ， 把 这 个 文件 修改 成 下 面 这 样 。 




















让 





<?xml version="1.0" encoding="utf-8" ?> <!-- @ --> 

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 
android:orientation="vertical" 
android:layout width="match_parent" 
android:layout_height="match_parent 
> <!-- @ --> 

<TextView 
android:layout_width="match_parent" 
android:layout_height="wrap_content 





大 


126 | 第 7 章 


android:text="GitHub Username:" 


/> 


<EditText 


android:layout _ width="match_parent" 


android:layout_height="wrap_content" 


android:id="@+id/username" 


/> 


<TextView 


android:layout _ width="match_parent" 


android:layout_height="wrap_content" 


android:text="GitHub Password:" 


/> 


<EditText 


android:layout _ width="match_parent" 


android:layout_height="wrap_content" 


android:id="@+id/password" 
android:inputType="textWebPassword" 
/> <!-- ©@ --> 


<Button 


android:layout _ width="match_parent" 


android:layout_height="wrap_content" 


android: text="Login" 
android:id="@+id/login" 
/> <!-- @ --> 


<TextView 


android:layout _ width="match_parent" 


android:layout_height="wrap_content" 


android:id="@+id/login_status" 


/> 














</LinearLayout> 
也 许 你 慢 怕 XML 文件 (我 就 是 这 样 )， 可 是 这 样 才 便 于 使 用 声明 的 方式 编写 Android 布 
局 ， 而 且 有 很 多 GUI 工具 提供 了 强大 的 XML 布局 文件 管理 功能 。 浏 览 一 遍 这 个 XML 文 
件 ， 我 们 可 以 较为 容易 地 理解 它 的 作用 。 
@ 整个 布局 放 在 LinearLayout 元 素 里 。 这 个 元 素 的 作用 很 简单 : 纵向 堆 又 里 面 的 各 个 元 


素 。 我 们 把 布局 的 高 度 和 宽度 设 为 match_parent， 肯 


es 
@ 把 密码 字段 的 类 型 设 为 密码 ， 庶 盖 里 面 输入 


这 个 XML 文件 中 ， 有 些 元 素 有 ID 属性， 这 样 我 们 就 能 在 Java 代码 中 访问 那些 元 素 ， 
例如 为 按钮 指派 处 理 函 数 ， 或 者 获取 用 户 在 字段 中 输入 的 文本 。 稍 后 会 演示 怎么 做 。 


可 以 点 击 





这 个 布局 占 满 整 个 屏幕 


， 添 加 前 文 所 述 的 元 素 : 显示 标注 及 用 于 输入 用 户 名 和 密码 的 两 对 TextView 和 



































“Design” 标 签 页 ， 切换 回 设计 模式 ， 查 








这 个 XML 文件 得 到 的 视觉 结 


的 内 容 。 
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登录 后 也 需要 布局 。 使 用 相同 的 方式 新 建 logged_in.xml 文件 
日 哪个 仓库 ， 要 有 一 个 大 的 文本 字段 用 于 输入 博客 文章 ， 还 要 有 一 个 按钮 用 





让 用 户 选 择 使 月 
于 提交 博客 文章 。 另 外 还 要 在 按钮 下 放 一 个 状态 框 ， 指 明文 








<?xml version="1.0" encoding="utf-8"?> 


。 登 录 后 呈现 给 用 户 的 布局 要 





全 是 否 成 功 保存 。 


<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 


android:orientation="vertical" 
android:layout_width="match_parent" 
android:layout_height="match_parent" 
> 
<TextView 
android: 
android: 


layout_width="match_parent" 
layout_height="wrap_content" 
android: text="Logged into GitHub" 
android:layout weight="0" 
android:id="@+id/status" /> 


<EditText 
android: 
android: 
android: 
android: 
android: 


/> 


layout_width="match_parent" 
layout_height="wrap_content" 
hint="Enter the blog repository' 
id="@+id/repository" 
layout_weight="0" 


<EditText 
android: layout_ width="match_parent" 
android: layout_height="wrap_content" 
android:hint="Enter the blog title" 
android:id="@+id/title" 
android:layout weight="0" /> 


<EditText 
android:gravity="top" 
android:layout_ width="match_parent" 
android:layout_height="match_parent" 
android:hint="Enter your blog post" 
android:id="@+id/post" 
android:layout weight="1" 


/> 


<Button 
android:layout_ width="match_parent" 
android:layout_height="wrap_content" 
android:layout weight="0" 
android:id="@+id/submit" 
android:text="Send blog post"/> 


</LinearLayout> 





写 过 main.xml 文件 之 后 ， 你 对 这 个 文件 里 的 大 部 分 代码 应 
入 ， 可 以 从 GitHub 中 附带 的 示例 仓库 里 复制 ) 。 





该 都 熟悉 了 (如果 不 想 自己 输 
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布局 XML 写 好 了 ， 接 下 来 可 以 测试 应 用 了 。 


7.3 自动 测试 Android 应 用 


Android 支持 三 种 测试 : 单元 测试 、 集 成 测试 和 用 户 界面 〈UI) 测试 。 单 元 测试 验证 结构 
非常 紧凑 的 独立 代码 片段 ， 而 集成 测试 和 UI 测试 验证 大 段 代 码 的 整体 行为 。 对 Android 来 
说 ， 集 成 测试 一 般 意味 着 要 实例 化 数据 管理 器 ， 或 者 让 应 用 内 的 多 个 组 件 交 互 ;， 而 UI 测 
试验 证 面向 用 户 的 元 素 ， 如 按钮 和 文本 字段 。 本 章 将 创建 一 个 单元 测试 和 一 个 UI 测试 。 


有 一 点 要 特别 注意 : 单元 测试 在 开发 设备 中 运行 ， 而 不 是 在 Android 设备 中 运行 。 而 UI 测 
试 在 Android 设备 (或 仿真 器 ) 中 运行 。 开 发 设备 中 运行 的 Java 解释 器 和 Android 设备 中 
运行 的 Dalvik 解释 器 可 能 有 细微 差别 ， 因 此 三 种 测试 都 要 编写 。 也 就 是 说 ， 至 少 要 写 一 种 
在 Android 设备 或 仿真 器 中 运行 的 测试 。 















































7.3.1 对 GitHub 客 户 端 做 单元 测试 
我 们 先 来 编写 单元 测试 。 因 为 单元 测试 在 开发 设备 中 运行 ， 所 以 测试 和 实现 代码 不 能 加 载 
任何 Android 类 。 这 一 限制 要 求 我 们 只 能 把 重点 放 在 GitHub API 上 。 我 们 将 定义 一 个 辅助 
类 ， 让 它 处 理 与 GitHub API 的 交互 ,但 是 它 对 Android 一 无 所 知 。 然 后 ， 编 写 测 试用 具 ， 
实例 化 这 个 类 ， 验 证 与 GitHub 的 交互 能 得 到 正确 的 结果 。 
































按理 说 ， 你 可 能 会 问 : 单元 测试 应 该 验证 API 调用 吗 ? 这 种 类 型 的 测试 运行 
速度 快 吗 ? 毕竟 软件 开发 者 很 快 就 会 忽视 运行 速度 慢 的 单元 测试 。 在 单元 测 
试 中 模拟 响应 数据 好 吗 ? 这 些 都 是 好 问题 ! 











为 了 编写 单元 测试 ， 我 们 要 把 构建 方式 (build variant) 改 为 单元 测试 。 在 Android Studio 
左 侧 的 纵向 选项 卡 中 找到 “Build Variants”， 点 击 打开 ， 然 后 把 “Test Artifact” 切 换 成 
“Unit Tests”。 在 项 目 视图 (如果 没有 选中 项 目 视 图 ， 点 击 纵 向 选项 卡 中 的 “Project”) 中 
展开 java 目录， 里面 有 个 后 面 带 有 “(test)” 的 目录 ， 这 是 存储 测试 的 目录 。 如 果 没有 这 个 
目录 ， 在 命令 行 中 创建 (可 以 使 用 这 个 命令 : mkdir -p app/src/test/java/com/example/ 
ghru)。 



































然后 ， 创 建 一 个 测试 文件 ， 将 其 命名 为 GitHubHelperTest,java， 再 写 和 人 下 述 代码 : 





package com.example.ghru; 
import com.squareup.okhttp.OkHttpClient; // ©@ 
import com.squareup.okhttp.Request; 


import com.squareup.okhttp.Response; 


import org.junit.Test; // @ 





Android 和 Git Data AP| | 129 


import java.util.Date; 


import static org.junit.Assert.assertTrue; 


/** 
* 编写 单元 测试 之 前 ,要 在 Build Variants 面 板 中 切换 Test Artifact 
*/ 
public class GitHubHelperTest { // ©®@ 
@Test 
public void testClient() throws Exception { 





String login = System.getenv("GITHUB_HELPER_USERNAME"); // ©@ 
String password = System.getenv("GITHUB_HELPER_PASSWORD"); 
String repoName = login + ".github.io"; 


int randomNumber = (int)(Math.random() * 10000000); 
String randomString = String.valueOf( randomNumber ); 
String randomAndDate = randomString + " "+ 

(new Date()).toString() ; // ©@ 


GitHubHelper ghh = new GitHubHelper( login, password ); // ©@ 
ghh.SaveFile(repoName, 

"Some random title", 

"Some random body text", 

randomAndDate ); 


Thread.sleep(3000); // ©@ 


String url = "https://api.github.com/repos/"+ // ©®@ 
login + "/" + repoName + "/events"; 
OkHttpClient ok = new OkHttpClient(); 
Request request = new Request.Builder() 

.url( url ) 

.build(); 
Response response = ok.newCall( request ).execute(); 
String body = response.body().string(); 


assertTrue( "Body does not have: " + randomAndDate, // © 
body.contains( randomAndDate ) ); 


} 

@ 首先 ， 导 入 用 于 发 送 HTTP 请 求 的 OkHttp 库 。 我 们 将 查看 仓库 的 事 但 
HTTP 访问 )， 验 证 对 GitHub API 的 调用 确实 发 送 到 GitHub 了 。 

@ 然后 ， 导 入 JUnit。 这 个 库 提 供 的 @Test 注解 用 于 告知 测试 运行 程序 哪个 方法 是 测试 函 
数 〈 即 在 测试 模式 中 应 该 当 作 测试 执行 )。 

@@ 定义 GitHubHelperTest 类 。 我 们 在 这 个 类 中 只 定义 了 一 个 测试 用 例 ， 即 testclient。 
此 处 使 用 erest 注解 告诉 JUnit， 这 是 一 个 测试 用 例 。 

@ 指定 登录 信息 和 测试 用 的 仓库 。 为 了 不 在 源码 中 写 入 密码 ， 此 处 使 用 环境 变量 获取 运 


让 


日 志 ( 





要 
二 
这 
呈 
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行 测试 时 指定 的 密码 。 

@ 然后 ， 构 建 一 个 随机 字符 串 。 我 们 把 这 个 独一无二 的 字符 串 当 作 提 交 说 明 使 用 。 这 是 
一 个 信 标 ， 我 们 使 用 它 验 证 提交 一 路 顺畅 ， 最 终 存 入 了 GitHub， 此 外 还 用 它 把 这 个 测 
试 创建 的 提交 与 其 他 测试 最 近 创 建 的 提交 区 分 开 。 

@ 现在 ， 进 入 测试 的 实质 阶段 : 传 入 登录 凭据 ， 实 例 化 那个 GitHub 辅助 类 ， 然 后 使 用 
SaveFile 函数 保存 文件 。 最 后 一 个 参数 是 稍 后 要 验证 的 提交 说 明 。 

@ 有 时 ，GitHub API 已 经 登记 了 提交 ， 但 是 API 返回 的 结果 中 却 没有 那 次 事 
秒 钟 能 解决 这 个 问题 。 

@ 接 下 来 ,使 用 OkHttp 库 发 送 HTTP 请 求 。 此 处 构建 了 一 个 用 于 获取 指定 仓库 的 事件 
的 URL。 如 果 事 件 类 型 是 推送 ， 那 么 事件 中 会 有 提交 说 明 。 巧 了 ， 这 个 仓库 是 公开 的 ， 

因此 无 需 验 证 身份 就 能 使 用 GitHub API 获取 数据 。 

@ 检查 HTTP 响应 的 主体 ， 验 证 里 面 有 那个 提交 说 明 。 


最 后 一 步 可 能 要 稍 做 研究 才能 写 出 来 。 使 用 cURL 请 求 事件 URL， 会 得 到 类 似 下 面 的 
数据 。 











山 
个 








FF 。 睡眠 几 






































$ curl https://api.github.com/repos/burningonup/burningonup.github.io/events 


[ 


{ 
"id": "3244787408"， 
"type": "PushEvent", 
"repo": { 
"id": 44361330 ， 
"name" : "BurningOnUp/BurningOnUp.github.io", 
"url": 
"https://api.github.com/repos/BurningOnUp/BurningOnUp.github.io" 
]， 
"payload": { 
"commits": [ 
"sha": "28f247973e73e3128737cab33e1000a7c281ff4b"， 
"author": { 
"email": "unknown@example.com", 
"name": "Unknown" 
}, 
"message": "207925 Thu Oct 15 23:06:09 PDT 2015", 
"distinct": true, 
a 
"https://api.github.com/repos/BurningOnUp/BurningOnUp.github.io/..." 
] 
} 
] 
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显然 ， 这 是 JSON。 可 以 看 出 ， 这 个 事件 的 类 型 是 PushEvent， 而 且 有 符合 随机 字符 串 格 
式 的 提交 说 明 。 上 述 JSON 可 以 构建 成 复杂 的 对 象 结构 ， 不 过 这 个 测试 检查 JSON 字符 串 
即 可 。 


7.3.2 ”对 Android 应 用 做 UI 测 试 


接 下 来 编写 一 个 UI 测试 。 这 个 测试 先 打 开 应 用 ， 找 到 用 户 名 和 密码 字段 后 ， 输 入 正确 的 
用 户 名 和 密码 ， 然 后 点 击 登录 按钮 ， 最 后 检查 UI 中 有 没有 “Logged into GitHub” 文 本 ， 
从 而 验证 是 否 成 功 登录 。 





Android 使 用 Espresso 框架 支持 UI 测试 。 前 面 配置 Gradle 时 已 经 安装 了 Espresso， 因 此 现 
在 可 以 编写 测试 。 测 试 要 继承 一 个 通用 的 测试 基 类 (ActivityInstrumentationTestCase2)， 
测试 类 中 定义 的 所 有 公开 函数 都 会 作为 测试 运行 。 




















在 Android Studio 的 “Build Variants” 面 板 中 选择 “Android Instrumentation Test”， 这 时 会 
出 现 一 个 带 有 “androidTest” 的 测试 目录 。 这 个 目录 里 的 测试 将 在 仿真 器 或 真正 的 设备 中 
运行 。 在 这 个 目录 中 新 建 一 个 文件 ， 将 其 命名 为 MainActivityTest.java。 





























package com.example.ghru; 


import android.support.test.InstrumentationRegistry; // © 

import android.test.ActivityInstrumentationTestCase2; 

import static android.suypport.test.espresso.Espresso.onView; 

import static android.support.test.espresso.action.ViewActions.*; 

import static android.support.test.espresso.assertion.ViewAssertions .matches ; 
import static android.support.test.espresso.matcher .ViewMatchers.*; 


public class MainActivityTest // @ 
extends ActivityInstrumentationTestCase2<MainActivity> { 


public MainActivityTest() { 
super( MainActivity.class ); // ©@ 
} 


public void testLogin() { // @ 
injectInstrumentation( InstrumentationRegistry. 
getInstrumentation() ); // © 
MainActivity mainActivity = getActivity(); 
String username = mainActivity // © 
.getString( R.string.github_helper_username ); 
onView( withId( R.id.usernane ) ) // @ 
.perform( typeText( username ) ); // ©@ 
String password = mainActivity 
.getString( R.string.github_helper_password ); 
onView( withId( R.id.password ) ) 
.perform( typeText( password ) ); 
onView( withId( R.id.login ) ) 
.perform( click() ); 
onView( withId( R.id.status ) ) // © 
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.Check( matches( withText( "Logged into GitHub" ) ) ); 


} 
} 


@ 导入 实 装 登记 禾 (为 应 用 的 测试 提 


絮 。 
@ 定义 一 个 测试 类 ， 继承 自 通 用 的 Ac 


@ Espresso 测试 的 构造 方法 需要 调用 
动 类 (这 里 是 MainActivity)。 





供 实 装 )、 基 类 ， 以 及 在 测试 中 用 于 下 定 断 言 的 匹配 


tivityInstrumentationTestCase2 类 。 


父 类 的 构造 方法 ， 并 在 参数 中 传 入 这 个 测试 使 用 的 活 


@ 此 处 测试 的 目的 是 验证 可 以 登录 GitHub ， 因 此 起 个 相关 的 名 称 。 
@ 然后 ， 加 载 实 装 登记 得， 再 调用 getActivity 方法 ， 这 样 方 能 实例 化 并 启动 活动 。 如 果 


这 两 步 要 在 多 个 测试 中 使 用 ， 很 多 
数 中 (以 便 在 每 个 测试 之 前 运行 )。 
中 直接 实现 那 两 步 。 

@ 凭据 一 定 不 能 存储 在 代码 仓库 里 ， 











Espresso 测试 会 将 其 写 入 一 个 使 用 @Before 注解 的 函 
这 里 ， 为 了 减少 函数 数量 ， 我 们 在 唯一 的 测试 函数 











因此 在 活动 上 调用 getstring 函数 ， 从 XML 资源 文 


件 中 获取 用 户 名 和 密码 。 稍 后 会 展示 这 个 机 密 文件 的 内 容 。 




















@ 获得 用 户 名 之 后 ， 将 其 输入 界面 中 的 文本 字段 里 。onView 函数 的 作用 是 与 视图 (例如 











按钮 和 文本 字段 ) 交互 。withId 函 
到 视图 后 ， 就 可 以 执 5 操作 (使 用 
个 文本 字段 中 输入 GitHub 用 户 名 。 














数 使 用 XML 布局 文件 中 的 资源 标识 符 查 找 视图 。 找 
perform 国 数 ) ， 例 如 输入 文本 。 这 一 串 调 用 在 第 一 














@ 输入 密码 ， 然 后 点 击 登录 按钮 ， 完 成 与 UI 的 交互 。 
@ 如 果 成 功 ， 那 么 会 看 到 “Logged into GitHub” 文 本 。 在 背后 ， 这 个 测试 会 验证 我 们 登 




















录 了 GitHub， 并 显示 了 成 功 登 录 的 结果 。 





为 了 给 测试 提供 用 户 名 和 密码 ， 而 且 不 把 凭据 写 入 源码 ， 我 们 要 在 资源 文件 夹 中 的 strings 





目录 里 创建 一 个 名 为 secrets.xml 的 文 介 


F， 然 后 写 入 下 述 代码 。 


<?xml version="1.0" encoding="utf-8"?> 


<resources> 


<string name="github_helper_login">MyUsername</string> 
<string name="github_helper_password">MyPwd123</string> 


</resources> 


接 下 来 要 在 .gitignore 文件 中 添加 一 个 排除 规则 ， 确 保 不 把 这 个 文件 纳入 源码 仓库 (快速 方 





式 是 执行 命令 echo "secrets.xmL" >> 


测试 目前 无 法 编译 ， 因 为 我 们 还 没 编 
Android Studio 中 运行 测试 。 








.gtitgnore ) 。 


写 应 用 的 其 他 部 分 呢 。 因 此 ， 这 里 暂时 不 讲 如 何在 
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下 











7.4 ”实现 应 用 


现在 可 以 为 应 用 编写 一 些 Java 代码 了 。 下 面 让 MainActivity 类 具 现 前 





package com.example.ghru; 


import 
import 
import 
import 
import 
import 
import 


public 


/** 初次 创建 活动 时 调用 


android 


android. 
android. 
android. 
android. 


os.Bundle; 


和 我 们 要 构建 应 用 ， 让 测试 通过 。 


.app.Activity; 
android. 
android. 


widget.Button; 
widget.LinearLayout; 
widget.EditText; 
widget.TextView; 


view.View; 


class MainActivity extends Activity 


@Override 
public void onCreate(Bundle savedInstanceState) 


} 


private void login() { 


} 


private void dopost() { 


} 


这 段 代 码 模拟 我 们 将 实现 的 功能 ， 二 

















| 


super .onCreate(savedInstanceState); 
setContentView( R.layout.main); 





鲁 定 义 的 布局 . 











Button login = (Button)findViewById( R.id.Login ); 
login.setOnClickListener(new View.0nCLickListener() { // © 
public void onClick(View v) { 


}); 


login(); // @ 


setContentView(R.layout. logged in); // ©@ 


Button submit = (Button)findViewById( R.id.submit ); 
submit.setOnClickListener(new View.OnClickListener() { 
public void onClick(View v) {//@ 


}); 


doPost(); 


TextView tv = (TextView)findViewById( R.id.post status ); // © 
tv.setText( "Successful jekyLL post" ); 








F 展 示 代 码 写 完 之 后 界 玫 











到底 是 什么 样子 。 
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@ 为 登录 按钮 注册 点 击 事件 的 处 理 函 数 。 

@ 点 击 登录 按钮 时 ， 调 用 Login() 函数 ， 触 发 登录 流程 。 

日 登录 后 ， 显 示 已 登录 布局 ， 让 用 户 撰写 博客 文章 。 

@ 为 提交 按钮 注册 点 击 事件 的 处 理 函 数 。 点 击 提交 按钮 时 ， 调 用 doPost() 函数 。 
@ doPost() 函数 更 新 应 用 底部 的 状态 消息 。 


虽然 代码 还 未 实现 全 部 功能 ， 但 是 应 用 可 以 编译 了 。 这 时 适合 试用 应 用 ， 验 证 UI 的 外 观 
是 否 恰当 。 登 录 表 单 如 图 7-4 所 示 。 











© 5554:Nexus_5_API_21 


GitHub Username: 





GitHub Password: 

















7-4: 简单 的 登录 UI 
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7.4.1 编写 登录 GitHub 的 代码 

现在 可 以 连接 GitHub API 了。 首先， 实现 Login() 函数 。 参 照 EGit 库 的 参考 文档 (https:// 
github.com/eclipse/egit-github/tree/master/org.eclipse.egit.github.core) ， 登 录 GitHub 的 代码 可 
以 简单 地 写成 下 面 这 样 。 





GitHubClient client = new GitHubClient(); 
client.setCredentials("Uys3r", "passwOrd"); 


然而 ， 运 行 这 段 代码 的 上 下 文 没有 代码 本 身 这 么 简单 。 除 非 使 用 后 台 线 程 ， 否 则 Android 
操作 系统 不 允许 运行 任何 连接 网 络 的 代码 。 如 果 你 不 是 Java 开发 者 ， 可 能 觉得 在 Java 
中 使 用 线程 很 麻烦 ， 其 实 不 然 ，Android SDK 提供 了 一 个 便于 管理 后 台 任 务 的 类 ， 名 
为 AsyncTask。 这 个 类 提供 了 几 个 入 口 点 ， 我 们 可 以 方便 地 进入 Android 操作 系统 管理 
的 线程 的 生命 周期 。 我 们 要 定义 一 个 类 ， 然 后 覆盖 AsyncTask 类 提供 的 两 个 国 数 : 第 一 
个 是 doInBackground() 函数 ， 它 把 操作 移 到 主线 程 之 外 ( 即 后 台 线 程 中 ) ， 第 二 个 是 
onPostExecute() 国 数 ， 它 在 UI 线程 中 运行 ， 用 于 把 doInBackground() 函数 的 结果 更 新 到 
UI 中 。 


在 实现 登录 功能 之 前 ， 需 要 更 新 MainActivity 类 中 的 onCreate 函数 。 登 录 按 钮 用 于 处 
理 登 录 操 作 ， 因 此 要 在 登录 按钮 上 注册 一 个 点 击 事件 的 处 理 函 数 ， 调 用 后 面 即将 定义 的 
LoginTask (AsyncTask 的 子 类 )。 













































































@Override 
pubLic void onCreate(Bundle savedInstanceState) 
四 
super.onCreate(savedInstanceState); 
setContentView(R.layout.main); 


Button login = (Button)findViewById( R.id.Login ); 
login.setOnClickListener(new View.OnClickListener() { 
public void onClick(View v) { 
EditText utv = (EditText)findViewById( R.id.username ); 
EditText ptv = (EditText)findViewById( R.id.password ); 
username = (String)utv.getText().toString(); 
password = (String)ptv.getText().toString(); // ©@ 
TextView status = 
(TextView)findViewById( R.id.login status ); 
status.setText( "Logging in, please wait..." ); // @ 
new LoginTask().execute( username, password ); //®©@ 


]); 





@ 从 UI 元 素 中 获取 用 户 名 和 密码 。 
@ UI 应 该 告知 用 户 ， 后 台 任 务 正在 处 理 登 录 操 作 ， 因 此 ， 我 们 获取 状态 文本 元 素 ， 然 后 
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更 新 里 面 的 文本 。 

@ 然后 ， 局 动 后 台 线 程 ， 处 理 登 录 操 作 。 这 一 行 代码 会 新 建 一 个 线程 ， 传 和 人 用户 名 和 密 
码 作为 参数 。 Android 会 代为 管理 这 个 线程 的 生命 周期 ， 例 如 在 主 UI 线程 之 外 启动 这 
个 新 线程 。 



































才 


下 ， 实 现 LoginTask 类 。 











cLass LoginTask extends AsyncTask<String, Void, Boolean> { //@ 
@Override 
protected Boolean doInBackground(String... credentials) { // @ 
boolean rv = false; 
UserService Us = new UserService(); 
us.getClient().setCredentials( credentials[0], credentials[1] ); 


try { 
User user = us.getUser( credentials[0] ); // 日 
rv = null != user; 


catch( IOException ioe ) {} 


return rv; 
} 
@Override 
protected void onPostExecute(Boolean result) { 
if( result ) { 
loggedIn(); // @ 
} 
else { // 9 
TextView status = (TextView)findViewById( R.id.login status ); 
status.setText( "Invalid login, please check credentials" ); 
} 
} 


@ 我 们 定义 的 这 个 类 继承 自 AsyncTask。 泛 型 签名 中 有 三 个 类 型 : String、Void 和 
Boolean。 它 们 分 别 是 传 给 入 口 点 的 参数 、 中 间 回 调和 最 终 回调 。 其 中 ,最终 回调 把 控 
制 器 交还 调用 线程 。 第 一 个 类 型 用 于 指定 实例 化 任务 所 需 的 参数 ， 我 们 要 为 后 台 任 务 
提供 用 户 名 和 密码 ， 而 根据 签名 ， 第 一 个 类 型 可 以 传 入 字符 串 数 组 。 在 函数 的 签名 中 ， 
省 略 号 表示 可 以 把 任意 多 个 参数 (这 叫 变 长 参数 ) 传 入 函数 。 在 函数 的 定义 体 中 ,我 
们 期 待 传 入 两 个 字符 串 ， 因 此 调用 函数 时 一 定 要 传 入 两 个 字符 串 。 

@ 在 doInBackground() 函数 中 ， 我 们 实例 化 UserService 类 。 这 个 类 是 对 GitHub API 的 
包装 ， 作 用 是 与 用 户 服务 API 调用 交互 。 为 了 获取 这 个 信息 ， 需 要 获取 服务 调用 的 客 
户 端 ， 然 后 把 用 户 名 和 密码 传 给 客户 端 。 这 几 行 代码 就 是 做 这 个 的 。 

@ 我 们 把 调用 getuser() 函数 的 代码 放 入 try 块 里 ， 因 为 getuser() 函数 可 能 会 抛 出 错误 
(比如 说 网 络 不 可 用 )。 其 实 无 需 使 用 User 对 象 获取 用 户 的 信息 ， 可 是 这 么 做 能 确保 用 
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户 名 和 密码 是 正确 的 ， 而 且 可 以 把 结果 存 入 返回 值 。 调 用 API 时 GitHub 才 会 使 用 我 们 
设置 的 凭据 ， 
@ 调用 的 函数 是 loggedIn()， 而 不 是 Login()， 这 样 能 更 准确 地 表明 此 时 已 经 登 引 


GitHub 。 





因此 我 们 要 访问 什么 东西 时 才能 验证 凭据 可 用 。 





@ 如 果 由 于 网 络 不 可 用 或 者 凭据 错误 而 导致 登录 失败 ， 那 就 在 状态 消息 中 体现 出 来 。 如 
果 用 户 愿 意 ， 那 么 可 以 重 试 。 


登录 成 功 后 ，LoggedIn 函数 会 更 新 UI， 然 后 把 文章 发 布 到 GitHub 中 。 





private void LoggedIn() { 


文章 。 


setContentView(R.layout.logged in); // © 


Button submit = (Button)findViewById( R.id.submit ); 
submit.setOnClickListener(new View.OnClickListener() { // @ 


呈现 已 登录 布局 ， 表 明确 已 登录 。 
然后 ， 为 提交 按钮 注册 点 击 事件 的 处 理 函 数 ， 这 样 提交 文章 后 可 以 在 GitHub 中 创建 


public void onClick(View v) { 


TextView status = (TextView) findViewById(R.id.login_ status); 
status.setText("Logging in, please wait..."); 


EditText post = (EditText) findViewById(R.id.post); // © 
String postContents = post.getText().toString(); 


EditText repo = (EditText) findViewById(R.id.repository); 
String repoName = repo.getText().toString(); 


EditText title = (EditText) findViewById(R.id.title); 
String titleText = title.getText().toString(); 


dopost(repoName, titleText, postContents); // @ 











@ 我 们 要 收集 用 户 提供 的 三 个 信息 : 文章 正文 、 文 章 标题 和 仓库 名 。 
@ 把 这 三 个 信息 传 给 doPost 函数 ， 执 行 异步 任务 。 





有 了 使 用 AsyncTask 类 的 经 验 之 后 ， 定 义 doPost() 国 数 应 该 顺手 了 。doPost() 函数 要 把 文 
章 提交 到 GitHub 中 ， 还 要 处 理 后 台 线 程 中 的 网 络 活动 。 




















private void doPost( String repoName, String title, String post ) { 





大 
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i 


new PostTask() .execute( username, password, repoName, title, post ); 


} 

class PostTask extends AsyncTask<String, Void, Bo 
@Override 
protected Boolean doInBackground(String... in 


String login = information[0]; 

String password = information[1]; 
String repoName = information[2]; 
String titleText = information[3]; 
String postContents = information[4]; 


Boolean rv = false; // @ 
GitHubHelper ghh = new GitHubHelper(login 
try { 
rv = ghh.SaveFile(repoName, titleText 
postContents, "GhRu Update"); // @ 
} catch (IOException ioe) { //©@ 


Log.d(ioe.getStackTrace().toString(), 
} 
return rv; 
} 
@Override 


protected void onPostExecute(Boolean result) 
TextView status = (TextView) findViewById 
if (resuLt) {//©@ 
status.setText("Successful jekyLL pos 


EditText post = (EditText) findViewBy 
post.setText(""); 


EditText repo = (EditText) findViewBy 
repo.setText(""); 


EditText title = (EditText) findViewB 
title.setText(""); 

} else { 
status.setText("Post failed."); 


} 


olean> { 


formation) { // ©@ 


，password); // © 


3? 


"GhRu" ) ; 


{ 


(R.id.status); 
t"); 


Id(R.id.post); 


Id(R.id.repository); 


yId(R.id.title); 


@ 首先 ， 获取 需 要 传 给 GitHub API 的 参数 。 注 意 ， 这 些 信息 不 是 从 UI 中 获取 的 。 后 台 





线程 无 权 访问 Android 的 UI 函数 。 


@ 这 个 函数 的 返回 值 是 true 或 false， 表 明 登 录 成 功 还 是 失败 (变量 rv 是 “return value” 
的 缩写 )。 在 一 切 未 定之 前 ， 我 们 假定 登录 失败 ， 因 此 先 把 rv 的 值 设 为 false。return 
语句 的 值 会 传 给 线程 生命 周期 中 的 下 一 个 阶段 ， 即 名 为 onPostExecute 的 函数 (这 是 生 
命 周 期 中 一 个 可 选 的 阶段 ， 我 们 使 用 这 个 阶段 把 操作 状态 报告 给 用 户 )。 
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@ 实例 化 GitHubHelper 类 。 我 们 应 该 熟悉 这 种 实例 化 和 使 用 方式 了 ， 因 为 单元 测试 中 也 
是 这 么 做 的 。 

@ 这 个 辅助 类 返回 true 或 false。 如 果 执 行 到 这 里 了 ， 这 就 是 最 终 的 返回 值 。 

日 为 了 处 理 错误 (大 多 数 情 况 下 是 网 络 错误 )， 我 们 把 对 SaveFile 函数 的 调用 代码 放 入 
try/catch 块 中 。 

@ onPostExecute() 函数 是 可 选 的 ， 在 后 台 任 务 结束 后 调用 。 这 个 函数 的 参数 是 前 一 个 函 
数 的 返回 值 。 如 果 doInBackground() 函数 的 返回 值 是 true， 说 明文 件 保存 成 功 ， 我 们 
就 更 新 应 用 的 UI。 


我 们 要 导入 支持 类 。Gradle 已 经 自动 把 EGit 的 JAR 文件 和 类 添加 到 项 目 中 了 。 我 们 要 在 
文件 的 顶部 ， 其 他 import 语句 的 下 面 添 加 下 述 import 语句 。 










































































import android.view.View; 

import android.os.AsyncTask; 

import org.eclipse.egit.github.core.service.UserService; 
import org.eclipse.egit.github.core.User; 

import java.io.IOException; 





现在 可 以 编写 把 数据 写 入 GitHub 的 代码 了 。 


7.4.2 ”编写 与 GitHub 交 互 的 代码 

最 后 一 步 ， 编 写 代 码 把 内 容 放 到 GitHub 中 。 这 不 是 件 简 单 的 事 ， 因 为 GitHub API 要 求 构 
建 Git 内 部 使 用 的 结构 。 如 果 想 进一步 了 解 这 个 结构 ， 推 荐 你 阅读 免费 开源 的 《精通 Git》 
一 书 (https://progit.org/)， 尤 其 是 最 后 一 章 “Git 内 部 原理 ” (http://dwz.cn/git-internals)。 


























简单 来 说 ，GitHub API 希望 我 们 创建 一 个 Git“ 树 ”"”， 然 后 在 树 里 放 一 个 blob 对 象 。 随 后 ， 
把 树 封装 到 “提交 ”对 象 里， 再 使 用 数据 服务 封装 程序 在 GitHub 中 创建 提交 。 此 外 ， 若 
想 把 树 写 入 GitHub， 需 要 知道 基 SHA 标识 符 ， 因 此 你 会 看 到 用 于 从 当前 分 支 最 后 一 个 树 
中 获取 SHA 的 代码 。 不 管 把 代码 推送 到 master 分 支 还 是 gh-pages 分 支 ， 这 部 分 代码 都 能 
正常 运行 ， 因 此 这 个 实用 类 支持 Jekyll 博客 。 


























我 们 将 定义 一 个 名 为 iLtHubHelper 的 辅助 类 ， 并 在 里 面 定义 一 个 函数 ， 用 于 把 文件 写 入 
仓库 。 


按照 GitHub API 的 要 求 ， 仓 库 里 存储 的 文件 要 使 用 Base64 或 UTF-8 编码 。Apache 基金 会 
在 Maven (EGit 库 也 是 从 这 个 软件 仓库 中 获取 的 ) 中 发 布 的 一 套 工 具 可 以 执行 这 种 编码 操 
作 ，Gradle 文件 已 经 安装 了 这 些 工具 (“commons-codec” 声 明 )。 


























此 处 先 在 SaveFile 国 数 中 调用 儿 个 国 数 ， 在 GitHub 中 创建 提交 。 这 些 函 数 都 有 一 定 的 复 





杂 度 ， 因 此 这 里 先 说 明 如 何 使 用 Git Data API 把 数据 存 入 GitHub。 


package com.example; 


import 


import 
import 
import 
import 
import 
import 
import 


import 
import 
import 
import 


android.util.Log; 


org.eclipse.egit.github.core.*; 


Ea 
org.eclipse.egit.github.core.client.GitHubClient; 
org.eclipse.egit.githuyub.core.service.CommitService; 
org.eclipse.egit.github.core.service.DataService; 
org.eclipse.egit.githuyub.core.service.RepositoryService; 
org.eclipse.egit.githuyub.core.service.UserService; 
org.apache.commons.codec.binary.Base64; 


java. text.SimpleDateFormat; 
java.util .Date; 
java.io.IOException; 
java.util.*; 


class GitHubHelper { 


String login; 
String password; 


GitHubHelper( String _login, String _password ) { 


} 


login = _login; 
password = _password; 


public boolean SaveFile( String _repoName, 

String _title, 

String _post, 

String _commitMessage ) throws IOException { 


post = _post; 


repoName = _repoName; 
title = _title; 
commitMessage = _commitMessage; 


boolean rv = false; 


generateContent(); 
createServices(); 
retrieveBaseSha(); 


if( nuLL != baseCommitSha && "" 
createBlob(); 
generateTree(); 
createCommitUser(); 
createCommit(); 
createResource(); 
updateMasterResource(); 
rv = true; 


!= baseCommitSha ) { 
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return TV， 





SaveFile 函数 执行 使 用 GitHub API 把 数据 写 和 仓库 的 各 个 步 又。 后面 会 一 一 定义 这 些 国 
数 。 可 以 看 出 ，SaveFile 函数 的 签名 与 单元 测试 中 调用 的 同名 函数 一 样 。 

















下 面 分 别 实现 GLtHubHelper 类 中 调用 的 各 个 函数 。 


7.4.3 ”编写 博客 内 容 


首先 ， 实 现 generateContent() 国 数 。 下 述 代码 片段 中 定义 的 国 数 用 于 生成 存 和 GitHub 仓 
库 里 的 内 容 : 








String commitMessage; // ©@ 
String postContentsWithYfm; 
String contentsBase64; 
String filename; 

String post; 

String title; 

String repoName; 


private void generateContent() { // @ 
postContentsWithYfn = // ©@ 
"---\n" + 
"Layout: post\n" + 
"published: true\n" + 
"title: '" + title + "'\n---\n\n" + 
post; 
contentsBase64 = //@ 
new String( Base64.encodeBase64( postContentsWithYfm.getBytes() ) ); 
filename = getFilename(); 


} 


private String getFilename() { 
String titleSub = title.substring( 0, // 9 
post.length() > 30 ? 
30 : 
title.length() ); 
String jekyllfied = titleSub.toLowerCase() // @ 
.replaceAll( "\\W+", "-") 
.repLaceALL( "\\W+$", "" ); 
SimpleDateFormat sdf = new SimpleDateFormat( "yyyy-MM-dd-" ); // @ 
String prefix = sdf.format( new Date() ); 
return "_posts/" + prefix + jekyllfied + ".nmd"; // ©@ 
} 


String blobSha; 
Blob blob; 
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可 以 看 出 ， 上 述 Java 代码 与 第 6 章 中 用 于 生成 文件 名 和 去 除 空格 的 Ruby 代码 有 很 多 相似 

之 处 。 

@ 首先 ， de 用 来 存储 要 存 入 GitHub 中 的 数据 ， 包 括 提交 说 明 、 带 有 
YAML 格式 头 部 元 信息 整 文章 、 编 码 成 Base64 的 文章 内 容 、 文 件 名 ， 以 及 调用 
SaveFile()E 六 人 I 人 i 妆 闪 即 文章 本 身 、 标 题 和 仓库 名 。 

名 generateContent 国 数 创建 文章 的 各 个 部 分 ，Base64 编码 的 全 部 内 容 ， 以 及 用 于 存储 内 
容 的 文件 的 文件 名 。 

@ 创建 YAML 格式 的 头 部 元 信息 (YEFM 的 详细 说 明 参 见 第 6 章 )。 我 们 把 布局 设 为 
post， 把 发 布 与 否 设 为 true。YFM 后 面 要 加 两 个 换行 。 

@ 使 用 Apache Commons 库 提 供 的 实用 类 把 博客 文章 的 内 容 编码 成 Base64 格式 。Git 仓库 
里 存储 的 内 容 使 用 UTF-8 或 Base64 格式 ， 因 为 这 是 文本 内 容 ， 所 以 也 可 以 使 用 UTF-8 
格式 ， 不 过 Base64 是 无 损 的 ， 无 需 担 心 内 容 损坏 。 

@ 接 下 来 ,在 getFilename() 函数 中 使 用 文章 的 前 30 个 字符 创建 标题 。 

@ 为 了 满足 Jekyll 对 文章 标题 的 格式 要 求 ， 把 标题 转换 成 小 写 ， 再 把 空格 替换 成 连 字 符 。 

@ Jekyll 要 求 日 期 的 格式 为 yyyy-MM-dd， 所 以 我 们 使 用 Java 原生 的 SimpleDateFormat 类 
创建 符合 格式 的 字符 串 。 

@ 最 后 ， 把 这 几 部 分 组 合 在 一 起 构成 文件 名 ， 再 在 前 面 加 上 Jekyll 存储 文章 的 目录 _posts。 


下 面 创建 把 提交 存 入 GitHub 的 必要 服务 。 



























































ee 


















































7.4.4 ” ”GitHub 服务 
接 下 来 ， 实 现 createServices() 函数 。 我 们 要 实例 化 好 儿 个 服务 (对 Git 协议 的 包 
装 )， 虽 然 不 会 立即 都 使 用 ， 但 是 存储 文件 过 程 中 的 几 个 步骤 会 分 别 用 到 。 这 些 服务 都 在 
createServices 国 数 中 实例 化 。 





RepositoryService repositoryService; 
CommitService commitService; 
DataService dataService; 


private void createServices() throws IOException { 
GitHubClient ghc = new GitHubClient(); 
ghc.setCredentials( login, password ); 
repositoryService = new RepositoryService( ghc ); 
commitService = new CommitService( ghc ); 
dataService = new DataService( ghc ); 
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顺便 说 一 下 ， 这 样 写 可 以 把 GitHub.com 的 端点 换 成 企业 版 的 端点 。 具 体 的 句法 参见 附录 A。 





7.4.5 ”从 仓库 和 分 支 中 获取 基 SHA 


现在 ， 实 现 retrieveBaseSha() 函数 。Git 仓库 是 有 向 非 循环 图 (Directed Acyclic Graph， 


























DAG)， 因 此 图 中 〈 几 乎 ) 每 一 个 节点 都 指向 另 一 个 提交 (如果 是 合并 提交 ， 那 么 可 能 
是 两 个 提交 )。 向 图 中 添加 内 容 时 ， 我 们 需要 在 图 中 找到 之 前 的 节点 ， 然 后 附加 新 节点 。 
retrieveBaseSha 函数 的 作用 就 是 如 此 : 查找 最 后 一 个 提交 的 SHA 散 列 值 ， 即 在 树 中 的 地 
址 。 为 了 找到 这 个 地 址 ， 应 用 需要 引用 仓库 ， 于 是 我 们 使 用 前 面 实例 化 的 仓库 服务 获取 引 
用 。 知 道 仓库 后 ， 还 要 在 正确 的 分 支 (通过 getBranch 函数 确定 ) 中 查找 。 

















private void createServices() throws IOException { 
GitHubClient ghc = new GitHubClient(); 
ghc.setCredentials( login, password ); 
repositoryService = new RepositoryService( ghc ); 
commitService = new CommitService( ghc ); 
dataService = new DataService( ghc ); 


} 


Repository repository; 
RepositoryBranch theBranch ; 
String baseCommitSha; 
private void retrieveBaseSha() throws IOException { 
// 从 Git 仓 库 的 当前 分 支 中 获取 基 SHA 
repository = repositoryService.getRepository(login, 
theBranch = getBranch(); 
baseCommitSha = theBranch.getCommit().getSha(); 








} 


public RepositoryBranch getBranch() throws IOException { 
List<RepositoryBranch> branches = 
repositoryService.getBranches(repository); 
RepositoryBranch master = null; 
// 迭代 分 支 列 表 , 查 找 gh-pages 或 master 
for( RepositoryBranch i : branches ) { 
String theName = i.getName().toString(); 
if( theName.equalsIgnoreCase("gh-pages") ) { 
theBranch = i; 
} 
else if( theName.equalsIgnoreCase("master") ) { 
master = i; 
} 
} 
if( null == theBranch ) { 
theBranch = master; 
} 


return theBranch; 




















repoName); 





基 SHA 十 分 重要 ,没有 它 就 不 能 创建 提交 并 把 提交 链接 到 现 有 的 提交 图 中 。 在 前 面 定 义 
的 SaveFile() 函数 中 ， 如 果 没 有 正确 获取 SHA 散 列 值 ， 提 交 步 又 就 会 终止 。 


7.4.6 创建 blob 


Git 仓库 中 的 内 容 以 blob 的 形式 存储 。createBlob 函数 先 把 内 容 存储 成 blob 对 象 ， 然 后 使 
用 dataService 将 其 存 和 仓库。 在 调用 dataService.createBlob 函数 之 前 ，blob 对 象 并 未 
真正 存 和 人 GitHub。 此 外 要 注意 ，blob 对 象 不 能 直接 链接 到 DAG 中 ， 而 要 通过 树 对 象 和 提 
交 对 象 与 DAG 关联 ， 如 下 所 示 : 











String blobSha; 
Blob blob; 
private void createBlob() throws IOException { 
blob = new Blob(); 
blob.setContent(contentsBase64); 
blob.setEncoding(Blob.ENCODING_ BASE64); 
bLobsha = dataService.createBlob(repository, blob); 


7.4.7 生成 树 


接 下 来 ， 实 现 用 于 生成 树 的 generateTree() 国 数 。 树 包装 blob 对 象 ， 并 主要 提供 指向 那 
个 对 象 的 路 径 。 如 果 与 操作 系统 对 比 ， 那 么 树 相当 于 文件 名 路 径 ， 而 blob 相当 于 索引 市 点 
(inode)。 数 据 服务 管理 器 会 使 用 仓库 名 和 基 SHA 地 址 (之 前 获取 的 ) 验证 这 是 进入 仓库 
的 有 效 入 口 。 创 建树 之 后 ， 要 设 定 必 要 的 树 属性 ， 例 如 树 的 类 型 (blob) 和 模式 (blob)， 
以 及 blob 对 象 的 SHA 和 大 小 。 然 后 ， 使 用 数据 服务 对 象 把 树 存 入 GitHub。 











Tree baseTree; 

private void generateTree() throws IOException { 
baseTree = dataService.getTree(repository, baseCommitSha); 
TreeEntry treeEntry = new TreeEntry(); 
treeEntry.setPath( filename ); 
treeEntry.setMode( TreeEntry.MODE BLOB ); 
treeEntry.setType( TreeEntry.TYPE_BLOB ); 
treeEntry.setSha(blobSha); 
treeEntry.setSize(blob.getContent().1length()); 
Collection<TreeEntry> entries = new ArrayList<TreeEntry>(); 
entries.add(treeEntry); 
newTree = dataService.createTree( repository, entries, 

baseTree.getSha() ); 
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7.4.8 创建 提交 


创建 内 容 的 步骤 快 结束 了 ， 接 下 来 要 使 用 createCommit() 函数 。 我 们 已 经 创建 了 存储 内 容 
的 blob， 也 (算是 ) 创建 了 存储 内 容 路 径 的 树 ， 不 过 既然 Git 是 版 本 控制 系统 ， 我 们 还 得 





存储 对 象 创建 人 和 说 明 。 
个 过 程 了 : 创建 提交 ， 寺 

















这 两 个 信息 存储 在 提交 对 象 里 。 做 完 前 面 几 步 之 后 ， 应 该 熟悉 这 
F 添 加 相关 的 元 数据 ， 即 提交 说 明 。 此 外 ， 还 要 指明 提交 用 户 。 然 

















后 ， 使 用 数据 服务 在 GitHub 仓库 里 正确 的 SHA 地 址 处 创建 提交 。 


CommitUser comm 


itUser; 


private void createCommitUser() throws IOException { 


UserService 
us.getClien 
commitUser 
User User = 
commitUser. 
String name 
if( null == 

name = 


} 


commitUser. 
String emai 
if( null == 
email = 
} 
commitUser. 


} 


Commit newCommi 


us = new UserService(); // © 
t().setCredentials( login, password ); 
= new CommitUser(); // @ 
us.getUser(); // © 

setDate(new Date()); 

= User .getName(); 

name || name.isEmpty() ) { // @ 
"Unknown"; 


setName( name ); // ©@ 
lL = user.getEmail(); 

email || email.isEmpty() ) { 
"unknown@example.com"; 


setEmail( email ); 


t; 


private void createCommit() throws IOException { 





// 创建 提交 


Commit comm 


it = new Commit(); // @ 


commit.setMessage( commitMessage ); 


commit.setA 


uthor( commitUser); // @ 


commit.setCommitter( commitUser ); 


commit.setT 
List<Commit 
Commit pare 
parentCommi 
listOfCommi 
Commit .setpP 
newCommit = 


ree( newTree ); 

> ListOfCommits = new ArrayList<Commit>(); // ©@ 
ntCommit = new Commit(); 

t.setSha(baseCommitSha); 

ts.add(parentCommit); 

arents(listOfCommits); 
dataService.createCommit(repository, commit); // © 


@ 创建 用 户 服 务 对 象 。 我 们 将 使 用 这 个 对 象 获取 已 登录 GitHub 的 用 户 数据 。 


@ 然后 ， 创 建 提交 用 户 


。 我 们 将 使 用 这 个 对 象 注 解 提交 对 象 (会 用 到 两 次 ， 一 次 指定 作 


者 ， 一 次 指定 提交 者 ) 。 
@ 使 用 用 户 服务 从 GitHub 中 获取 用 户 。 
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@ 尝试 获取 已 登录 用 户 的 名 字 。 如 果 没 有 名 字 (用 户 没 在 GitHub 个 人 资料 中 设置 )， 使 
用 “Unknown”。 然 后 ， 把 名 字 存 入 提交 用 户 对 象 。 

@ 使 用 相同 的 方式 设 定 提交 用 户 的 电子 邮件 地 址 。 

@ 定义 createCommit 国 数 ， 创 建 提交 对 象 。 

@ 作者 和 提交 者 都 要 使 用 ， 因 此 传 入 createCommituser 函数 中 创建 的 提交 用 户 。 

@ 接 下 来 ， 生 成 提交 列表 。 我 们 只 会 使 用 一 个 提交 ， 但 是 你 可 能 还 记得 ， 一 个 提交 可 以 


有 多 个 父 提交 〈 例 如 合并 )， 因 此 要 指定 一 个 或 多 个 父 提交 。 创 建 提交 列表 ， 创 建 一 个 
父 提交 ， 再 设置 前 面 得 到 的 基 SHA， 然 后 指明 这 是 新 提交 的 父 提交 。 
@ 最 后 ， 使 用 数据 服务 对 象 创建 提交 。 























7.4.9 更 新 上 游资 源 
最 后 ， 更 新 分 支 引用 ， 让 它 指向 新 提交 的 SHA。 








TypedResource commitResource; 

private void createResource() { 
commitResource = new TypedResource(); // © 
commitResource.setSha(newCommit.getSha()); 
commitResource.setType(TypedResource.TYPE_COMMIT); 
commitResource.setUrl(newCommit.getUrl()); 


} 


private void updateMasterResource() throws IOException { 
Reference reference = 
dataService.getReference(repository, 
"heads/" + theBranch.getName() ); // @ 
reference.setObject(commitResource); 
dataService.editReference(repository, reference, true) ; // 日 





@ 首先 ， 创 建新 提交 资源 。 然 后 ， 关 联 新 提交 的 SHA， 指 明 这 个 资源 的 类 型 是 提交 ， 然 
后 把 提交 资源 与 新 提交 的 URL 链接 起 来 。 

@ 使 用 数据 服务 对 象 从 GitHub 中 获取 当前 分 支 的 引用 。 为 了 获取 分 支 引 用 ， 要 在 分 支 前 
加 上 “heads”( 前 一 步 已 经 知道 分 支 ) 。 

@ 最 后 ， 更 新 分 文 引 用 ， 指 向 这 个 新 提交 资产 。 














以 上 是 使 用 Git Data API 向 GitHub 中 添加 数据 的 全 部 代码 。 干 得 漂亮 ! 


7.4.10 通过 全 部 测试 
代码 写 完 了 ， 下 面 要 确保 测试 能 通过 。 
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我 们 要 配置 测试 ， 让 测试 在 Android Studio 中 和 运行。 点击 左 侧 纵向 选项 卡 里 的 “Build 
Variants”， 在 “Test Artifact” 中 选择 “Unit Tests”。 0 ， 点 击 “Run” 菜 单 ， 选 择 “Edit 
configurations”。 点 击 加 号 ， 选 择 “JUnit”。 此 时 会 显示 一 个 界面 ， 让 你 创建 单元 测试 的 运 
行 配置 。 首 先 ， 点 击 “Use classpath of module" ， 选 择 “app”。 确 保 “Test Kind” 选 中 的 是 
“Class”， 然 后 点 击 “Class” 字 上段 右 侧 的 选择 器 ， 会 显示 出 GitHubHeLperTest.java 测试 类 。 
我 们 需要 将 用 户 名 和 密码 存储 为 环境 变量 ， 所 以 点 击 添加 这 两 个 环境 变量 。 最 终 的 配置 如 
图 7-5 所 示 。 





















































DGiY | ee a 
CDHG* % eae Run/Debug Configurations 有 a 
DohRu2 ) Caapp) Dsre 
+ 一 国 交 a^Y 口 上 Name: JUnit Test Share Sinleinsance ony 
» 请 Android Application i 
》 雪 Androld Tests (TET Code Coverage Loos 奖 x| 理 
国 Unit Test Test kind: Class Ee none 
rn Class: com example ghru GitHubHelperTest 
9 
Ea & 
VM options: -ea 国 全 
加 
Working directory: /Users/xrdawson/Projects/GhRu2 百 
转 ei ‘propert] 一 - 
_ 启 snde-wap 二 Environment variables:。 41ELPER_PASSWORD=mypPwd123:CITHUR_HELPER_USERNAME=myUsemame: = 站] 
| Use classpath of mod... [3 app 
Test Artifact: unit 
本 Use alternative JRE: > 
Wodule 
Jraar | 
日 app Tl 
| Before launch: Make 8 
引 Wh Make 呈 
四 
中 2 
a 
E + 2 
. Show this page 日 
加 各 
友 & 
PP4Run 5Debt@ > Kanon FT FEradle Console 
= | ppy ES 
国 Gradle buildfinishedin ntext> 安县 











7-5: 创建 单元 测试 配置 


接 下 来 ， 创 建 UI 测试 配置 。 在 “Build Variants” 标签 页 中 把 “Test Artifact” 切 换 成 
“Android Instrumentation Tests”。 然 后 ， 点 击 “Run” 菜 单 ， 选 择 “Edit configurations”。 点 
击 加 号 ， 这 一 次 选择 “Android Tests”"。 在 “Module” 中 选择 “app”， 然 后 选择 “android. 
support.test.runner.AndroidJUnitRunner” 作 为 实 装 运行 程序 。 你 可 以 选择 任何 设备 、 仿 真 器 
或 实体 设备 (如果 有 的 话 )。 给 配置 命名 ， 如 “Android Test”。 


运行 测试 的 方法 是 ， 先 切换 到 正确 的 测试 项 目 ， 然 后 点 击 “Run” 菜 单 ， 选 择 “Debug”， 
再 选择 正确 的 测试 配置 。 我 们 可 以 在 Android Studio 中 设置 断 点 ， 逐 行 运行 测试 或 实现 
代码 。 

运行 测试 时 ， 我 发 现在 不 同 的 构建 方式 之 间 切 换 很 麻烦 ， 因 此 ， 如 果 愿 意 的 话 ， 可 以 使 用 
命令 行 (这样 就 不 用 切换 构建 方式 了 )。 




















$ GITHUB_HELPER_USERNAME=MyUsername \ 
GITHUB_HELPER_PASSNORD=MyPwd123 \ 
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./gradlew testDebugUnitTest 


:app:mockabLeAndrotdJar UP-TO-DATE 
:app:assembleDebugUnitTest UP-TO-DATE 
:app:testDebugUnitTest UP-TO-DATE 


BUILD SUCCESSFUL 
$ ./gradlew connectedAndroidTest 


:app:compileDebugAndroidTestNdk UP-TO-DATE 
:app:compileDebugAndroidTestSources 
:app:preDexDebugAndroidTest 
:app:dexDebugAndroidTest 
:app:packageDebugAndroidTest 
:app:assembleDebugAndroidTest 
:app:connectedDebugAndroidTest 


BUILD SUCCESSFUL 

















在 Android Studio 的 测试 运行 程序 窗口 里 会 看 到 类 似 的 结果 。 测 试 通过 了 ， 应 用 也 开发 
完了 。 





如 果 想 深入 学 习 如 何在 Android 中 使 用 GitHub API， 可 以 看 一 下 Teddy Hyde 
(https://github.com/xrd/TeddyHyde.git，Google Play 应 用 商店 中 也 有 )。 该 应 
用 使 用 OAuth 登录 GitHub， 为 Jekyll 博客 提供 了 更 丰富 的 编辑 功能 。 











7.5 小 结 


本 章 所 编写 的 应 用 可 以 发 布 Jekyll 博客 ， 添 加 文章 后 ， do edn 这 个 
小 应 用 做 的 事 还 挺 多 的 ， 可 以 把 文件 名 改 为 正确 的 格式 ， 还 可 以 编码 提交 给 GitHub 的 数 
据 。 我 们 还 编写 了 单元 测试 和 UI 测试， 用 来 验证 功能 。 














下 一 章 将 使 用 CoffeeScript 创建 一 个 聊天 机 器 人 ， 通 过 Activity API 邀请 聊天 室 里 的 成 员 审 
查 拉 取 请 求 。 
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第 8 和 章 


CoffeeScript、Hubot 和 Activity AP| 





GitHub 曾 在 宣传 语 中 称 自 己 为 “社交 编程 ”工具 ， 不 过 这 种 表述 已 经 删除 了 。 然 而 ,“ 社 
交 ” 仍 是 GitHub 所 提供 服务 的 核心 思想 ， 我 们 可 以 使 用 Activity API 访问 GitHub 的 社交 
功能 。 











本 章 通过 实现 一 个 聊天 机 器 人 探索 Activity API。 你 可 能 觉得 奇怪 ， 机 器 人 有 违 社交 精神 ， 
为 什么 要 使 用 机 器 人 呢 ? 其 实 ， 我 们 要 开发 的 是 一 个 合理 利用 社交 API 的 社交 机 器 人 。 
Hubot 是 一 个 易于 扩展 的 聊天 机 器 人 ，GitHub 用 户 使 用 它 记 录 并 自动 执行 任务 ， 还 用 它 在 
互联 网 中 做 些 有 趣 的 事情 。 如 果 有 那么 一 个 机 器 人 能 胜任 与 GitHub Activity API 的 交互 ， 
那 一 定 是 Hubot。 按 照 Hubot 网 站 (https://hubot.github.com/) 的 说 法 ， 它 是 一 个 “能 改善 
生活 的 可 定制 机 器 人 ”。 


























8.1 Activity API 


Activity API 包含 : 





。 通知 (各 种 事件 中 提 到 用 户 的 评论 ) 

。 加 星 工 具 (GitHub 的 “加 星 ” 相 当 于 Facebook 的 “点 赞 ”"， 表 示 认 同 或 感 兴 趣 ) 
。 关注 (跟踪 GitHub 数据 的 一 种 方式 ) 

。 事件 (高 层次 的 活动 流 ， 供 用 户 关注 其 他 用 户 的 活动 ) 
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Activity API 也 包含 订阅 源 。 虽 然 把 订阅 源 划 归 给 了 Activity API， 但 是 订阅 




















源 不 能 像 API 那样 通过 编程 操作 ， 因 此 本 章 不 做 说 明 。 这 里 所 说 的 订阅 源 其 
实 是 Atom 订阅 产 ， 交 互 性 不 强 ， 是 与 RSS 订阅 源 类 似 的 静态 订阅 源 ， 可 以 
使 用 Atom 客户 端 订 阅 。 


8.2 ”让 拉 取 请 求 得 到 各 方 认同 


我 们 将 为 Hubot 构建 一 个 扩展 。 构 建 好 之 后 ，Hubot 将 变 身 能 处 理 下 述 事项 的 机 器 人 : 











。 使 用 GitHub Activity API 订阅 通知 ， 监 听 拉 取 请 求 事件 ; 

。 邀请 聊天 室 里 的 人 评论 拉 取 请 求 ; 

。 确保 机 器 人 与 GitHub 之 间 的 通信 是 加 密 传 输 的 〈 可 惜 有 缺陷 ) ; 
。 从 外 部 服务 (借助 Slack API) 中 获取 重要 信息 ， 

。 自动 化 测试 完全 覆盖 所 有 功能 ， 

。 易于 模拟 API 和 服务 的 输入 输出 ，; 
。 便于 部 署 到 主流 PaaS (Heroku)。 

















Hubot 为 这 个 聊天 机 器 人 提供 了 骨架 。 我 们 将 扩展 Hubot， 添 加 上 述 功能 。 从 这 个 过 程 中 
你 可 以 看 出 把 这 些 功能 集成 到 一 个 机 器 人 中 ， 让 它 去 解决 实际 问题 是 多 么 简单 。 


8.2.1 注意 事项 和 局 限 

如 果 想 稳定 地 运行 Hubot， 那 就 要 把 它 托 管 到 服务 器 中 。Hubot 是 使 用 NodeJS 开发 的 ， 因 
此 要 使 用 支持 NodeJS 的 主机 服务 。 我 们 要 通过 公 网 卫 地 址 开放 Hubot (不 能 放 在 防火 墙 
后 面 )， 因 为 它 需 要 从 GitHub 接收 通知 。 不 过 ，Hubot 不 一 定 非得 托管 在 公开 的 服务 器 中 ， 
如 果 Hubot 不 需要 从 外 界 接 收 数据 ， 可 以 把 它 托管 在 私有 的 内 部 服务 器 中 。 


托管 Hubot 最 简单 、 最 便宜 的 服务 是 Heroku。 生 成 Hubot 之 后 ， 只 需 使 用 Git 把 它 推 送 到 
Heroku 中 就 能 免费 发 布 聊 天 机 器 人 。 本 章 后 文 会 讲解 这 些 步骤 。 

















Hubot 支持 众多 聊天 端点 ， 可 以 连接 几乎 任何 流行 的 聊天 服务 和 协议 ， 包 括 了 下 C、XMPP 
以 及 很 多 收费 服务 ， 例 如 Gchat、Basecamp， 甚 至 Twitter。Slack 是 聊天 服务 领域 的 新 军 ， 
虽然 初 入 此 行 ， 但 是 Slack API 很 牢靠 ， 而 且 可 以 简单 直接 地 把 Slack 服务 与 第 三 方 客户 端 
连接 起 来 。 我 们 这 个 聊天 机 器 人 将 使 用 Slack 作为 端点 。 








下 面 来 创建 Hubot， 然 后 配置 ， 让 它 使 用 Slack。 


8.2.2 ”创建 常规 的 Hubot 
搭建 Hubot 机 器 人 之 前 ， 要 先 安装 NodeJS， 方 法 参见 附录 B。 安 装 好 之 后 ， 执 行 下 述 命 
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令 ， 在 一 个 目录 中 创建 Hubot 的 骨架 。 





npm install -g generator-hubot © 
mkdir slacker-hubot @ 

cd slacker-hubot/ 

yo hubot © 

npm install hubot-slack --save @ 


LT LT LT LT LT 





你 可 能 对 这 些 命令 不 熟悉 ， 下 面 说 明 其 中 几 个 重要 的 命令 。 











@ npm 是 为 NodeJS 安装 包 的 工具 (参见 附录 B)。npm instatL -9 generator-hubot 命令 
安装 一 个 名 为 yeoman 的 命令 行 工 具 和 用 于 生成 Hubot 的 yeoman 插件 。 

@ 你 应 该 新 建 一 个 目录 ， 然 后 进入 其 中 ， 把 创建 的 Hubot 放 在 完全 独立 的 地 方 。 

日 执行 yo hubot 命令 ,运行 生成 器 ， 生 成 Hubot 机 器 人 所 需 的 最 少量 的 文件 。 

@ 然后 安装 Slack 适配器 ， 并 把 包 保 存 到 package.json 文件 里 。 











至 此 ， 我 们 创建 了 一 个 简单 的 Hubot 机 器 人 ， 下 面 该 创建 Hubot 赖 以 生存 的 Slack 网 站 了 。 


8.2.3 注册 Slack 账 户 
创建 Slack 网 站 的 第 一 步 是 ， 访 问 https://slack.com/， 并 注册 账户 。Slack 网 站 按 组 织 划 分 ， 
因此 要 为 Slack 网 站 提供 URL 前 级 。 通 常 ， 这 是 你 所 在 组 织 的 名 称 。 


命名 频道 
创建 好 Slack 网 站 之 后 ， 需 要 创建 一 个 频道 ， 如 图 8-1 所 示 。 











# general 


Create a channel... 














8-1: 在 Slack 网 站 的 侧 边栏 中 创建 一 个 频道 


频道 的 名 字 随 便 取 ， 不 过 最 好 起 个 易 记 的 名 字 ， 而 且 要 表明 这 个 频道 用 于 讨论 重要 事项 。 
你 可 以 使 用 “PR Discussion” 这 样 的 名 字 ， 以 此 表明 这 个 频道 是 讨论 拉 取 请 求 的 。 简 单 起 
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见 ， 我 们 将 使 用 “#general” 这 个 名 字 。 点 击 创建 频道 的 链接 后 会 弹出 一 个 界面 ， 让 你 输 
入 名 字 和 可 选 的 描述 。 创 建 好 频道 之 后 ， 会 看 到 “Add a service integration ”链接 ， 如 图 


8-2 所 示 。 





#hubot 


This is the very beginning of the #hubot channel, which you created today. 


PSetapurpose “中 Add aservice integration ® Invite others to this channel 











图 8-2: 把 服务 集成 到 Slack 中 
Slack 文 持 集成 众多 服务 ， 其 中 就 有 Hubot， 如 图 8-3 所 示 。 





全 


L- 
本 


小 lh 
四 





Scalable customer support software. 


Heroku 
Cloud application deployment and hosting. 


Honeybadger 
Errorand performance monitoringforRuby. 


Hubot 
GitHub's scriptable chat bot. 


IFTTT 
Automated connections between web services. 


Intercom 
The easiest way to see and talk to your users. 





图 8-3:，Slack 的 服务 集成 选项 


选择 Hubot， 





此 时 会 进入 集成 设置 界 画 


Slack 会 自动 生成 一 个 身份 验证 令 牌 ， 用 于 验证 与 Hubot 的 连接 。 这 个 令 牌 可 以 吊销 ， 
实 图 8-4 中 的 令 牌 已 经 吊销 了 ，Slack 无 法 再 使 用 它 验证 身份 。 如 果 不 小 心 把 这 个 令 牌 公开 











o 





了 ， 可 以 在 这 个 界面 吊销 并 重新 分 配 令 牌 。 





二 


此 外 ， 还 要 指定 名 称 。 我 们 把 名 称 设 为 “probof " 。 如 果 愿 意 ， 可 以 修改 Hubot 对 应 的 头 
像 。( 这 些 设置 如 图 8-4 所 示 。) 
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This integration will allow your Hubot instance to connect and interact with your Slack team. 


Setup Instructions 


Download and install the SlackHubotadapteron amachinethat has persistentaccesstotheinternet Ifyou don't have one, 
Heroku is easiest, andthereareinstructionsonthe adapter page. 


Theadapterwillwantan APltoken. Set it with the following environment variable: 


HUBOT_SLACK_TOKEN=xoxb-3295776784-nZxL1H3nyLsVcgdD29r1PZCq 


Integration Settings 


APIToken 


The Hubotadapter needs an API 


xoxb-3295776784-nZxl1H3nyLsVcgdD29r1PZCq 
token. 


Regenerate 


Customize Name 


Choosethe usernamefor this Hubot. probot 


Customize Icon 
Change the icon used for this Hubot. 人 


Change Icon 











8-4: Slack 中 配置 Hubot 的 页 面 


继续 操作 之 前 记得 要 保存 设置 。 


8.2.4 在 本 地 运行 Hubot 

最 终 ， 我 们 将 在 服务 器 中 运行 Hubot， 不 过 Hubot 也 能 在 有 防火 墙 保护 的 笔记 本 电脑 中 
运行 。 开 发 初期 ， 在 测试 和 开发 机 器 人 的 过 程 中 经 常会 有 改动 ， 此 时 可 能 想 在 本 地 运行 
Hubot。 其 实 ， 防 火 墙 之 后 的 Hubot 功能 几乎 没有 损失 ， 唯 有 一 点 不 足 : 显而易见 ， 它 无 
法 访问 外 部 服务 。 我 们 最 终 的 目的 是 让 经 过 配置 的 GitHub 在 有 拉 取 请 求 创建 时 给 我 们 发 
送 事 件 ， 而 放 在 防火 墙 之 后 的 Hubot 接收 不 到 这 些 事件 。 除 此 之 外 ， 本 地 运行 的 Hubot 几 
平 所 有 功能 都 能 用 ， 而 且 能 提升 开发 的 速度 。 


若 想 在 本 地 运行 ， 则 要 在 命令 行 中 指定 变量 。 












































$ HUBOT_SLACK_TOKEN=xoxb-3295776784-nZxL1H3nyLsVcgdD29r1PZCq \ 
./bin/hubot -a slack 


这 个 命令 指定 使 用 Slack 适配器 运行 Hubot 脚本 。Slack 适配器 知道 如 何 与 Slack.com 服务 
交互 。 为 了 提供 Slack 适配器 所 需 的 身份 验证 令 牌 ， 我 们 在 命令 的 开头 通过 环境 变量 指定 。 
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1. 首次 对 话 

机 器 人 创建 好 了 ， 正 在 Slack 网 站 的 #general 房间 里 待命 。 进 入 #eeneral 房间 ， ws 

Hubot 的 名 字 和 命令 ， 例 如 the rules， 确认 Hubot 已 经 正确 连接 了 。 假 如 Hubot 的 名 字 
“probot”， 应 该 输入 probot the rules。 此 时 ， 机 器 人 会 显示 如 图 8-5 所 示 的 对 话 。 




















DOD:: 
the rules 
probot 
1.Arobot may not injure a human being on through inaction, allow ahuman being to come to harm. 


2. A robot must obey any orders given to it by human beings, except where such orders would conflict with the First Law. 
3. A robot must protect its own existence aslong as such protection does not conflict with the First or Second Law. 











8-5: Hubot 内 置 的 应 答 


我 们 看 到 ，Hubot 打印 出 了 自己 遵守 的 规则 ( 源 自 Isaac Asimov 于 1942 年 发 表 的 短篇 小 说 
《 环 舞 》) 。 


2. 了 解 Hubot 支 持 的 命令 
Hubot 支持 众多 原生 命令 ， 如 果 想 把 这 些 命 令 列 出 来 ,输入 help， 如 图 8-6 所 示 。 











口 : 
help 


全 slackbot 
slackbot adapter - Reply with the adapter 

slackbot animate me <query> - The same thing as image me , except adds afew parameters to try to return an animated GIF instead. 
slackbot echo <text> - Reply back with <text> 
slackbot help - Displays all of the help commands that slackbot knows about. 
slackbot help <query> - Displays all help commands that match <query>. 
slackbot image me <query> - The Original. Queries Google Images for <query> and returns a random top result. 
slackbot map me <query> - Returns a map view of the area returned by query. 











8-6: 列 出 Hubot 支持 的 命令 





pug me 命令 很 受 欢 迎 。 很 多 刚 接 触 Hubot 的 人 往往 会 沉浸 几 小 时 ， 浏 览 巴 哥 犬 的 朝 图 。 
上 瘤 了 1! 





计 
江 











8.3 ”部 署 到 Heroku 


至 此 ， 我 们 成 功 地 在 本 地 运行 了 Hubot。 我 们 可 以 把 机 器 人 部 署 到 Heroku， 让 它 持 续 运 
行 ， 即 使 关上 笔记 本 电脑 也 不 受 影响 。 





设置 Heroku 


使 用 Heroku 之 前 要 注册 账户 。Heroku 有 免费 套餐 ， 我 们 接 下 来 要 做 的 所 有 事情 使 用 这 个 
套餐 就 行 。 创 建 账户 之 后 ， 访 问 https://toolbelt.heroku.com/， 下 载 并 安装 Heroku 工具 集 。 


尾 
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这 个 工具 集中 有 一 系列 用 于 管理 Heroku 应 用 的 工具 。 在 此 之 前 ， 要 按照 第 1 章 所 述 的 方 
式 安装 Ruby。 




















如 果 你 的 聊天 机 器 人 能 按照 前 一 节 所 述 的 指令 工作 ， 那 么 基本 上 可 以 部 署 到 Heroku 了 。 
我 们 将 使 用 Heroku 工具 集 添加 与 前 面 一 样 的 环境 变量 。 除 了 Slack 的 身份 验证 令 牌 之 
外 ， 我 们 还 要 配置 网 站 的 URL。Heroku 会 根据 项 目的 名 称 生 成 URL ( 即 这 里 的 inqry- 
chatbot)， 只 要 名 称 没 被 别人 占用 ， 我 们 就 可 以 自行 命名 。 











$ heroku create inqry-chatbot 

$ heroku config:add HEROKU_URL=https://inqry-chatbot.herokuapp.com/ 

$ heroku config:add HUBOT_SLACK_TOKEN=xxbo-3957767284-ZnxLH1n3ysLVgcD2dr1PZ9Cq 
$ git push heroku master 

Fetching repository, done. 

Counting objects: 5, done. 

Delta compression using up to 8 threads. 

Compressing objects: 100% (3/3), done. 

Writing objects: 100% (3/3), 317 bytes | 0 bytes/s, done. 

Total 3 (delta 2), reused 0 (delta 0) 


----- > Node.js app detected 
----- > Requested node range: 0.10.x 


----- > Compressing... done, 6.8MB 
和 > Launching... done, v9 
https://inqry-chatbot.herokuapp.com/ depLoyed to Heroku 


To git@heroku.com:inqry-chatbot.git 
d32e2db..3627218 master -> master 


如 果 想 排除 Hubot 的 故障 ， 可 以 执行 heroku log 命令 ， 查 看 应 用 的 日 志 ， 例 如 heroku 
Logs -t 


o 


$ heroku Logs -t 

2014-11-18T07:07:18.716943+00:00 app[web.1]: SuccessfuLLy "connected ' 

as hubot 

2014-11-18T07:07:18.576287+00:00 app[web.1]: Tue, 18 Nov 2014 07:07:18 

GMT connect deprecated limit: Restrict request size at location of 

read at 
node_modules/hubot/.../express/.../connect/.../middleware/multipart.js:86:15 


在 聊天 室 中 输入 的 命令 会 以 事件 的 形式 体现 在 Heroku 的 日 志 中 。 利 用 这 一 点 ， 我 们 可 以 
确认 机 器 人 有 没有 正确 连接 Slack。 


此 外 ， 你 可 能 还 想 把 仓库 推送 到 GitHub 中 。Heroku 除了 托管 线 上 应 用 之 外 ， 还 会 存储 
Hubot 机 器 人 完整 的 Git 仓库 (尽管 Hubot 努力 表现 ， 说 到 底 只 不 过 是 一 个 NodeJS 应 
用 )。Heroku 可 以 托管 Hubot 机 器 人 的 全 部 源码 ， 但 是 与 GitHub 相 比 ， 缺 少 一 些 额 外 工 
具 ， 如 用 户 管理 。 鉴 于 此 ， 我 们 应 该 在 GitHub 中 托管 源码 仓库 ， 这 样 便 于 团队 成 员 为 聊 























天 机 器 人 开发 新 功能 。 在 本 地 构建 并 测试 之 后 ， 我 们 再 使 用 Git 工作 流程 把 机 器 人 部 署 到 
Heroku 中 。 








至 此 ， 我 们 安装 了 Hubot， 也 创建 了 机 器 人 。 下 面 该 探索 Activity API 了 ， 我 们 要 决定 如 何 
实现 前 面 计 划 的 扩展 。 


8.4 ”Activity API 概 述 


Activity API 的 核心 是 通知 ， 类 似 于 社交 网 站 常见 的 那 种 通知 ， 即 活动 时 间 线 中 的 重要 事 
件 。 在 GitHub 中 ， 活 动 事件 通常 是 指 开发 者 日 常 的 重要 操作 ， 例 如 把 提交 推送 到 远程 仓 
库 ， 在 仓库 的 讨论 组 中 提问 ， 或 者 把 工 单 分 配给 某 个 开发 者 审阅 。 


团队 成 员 不 用 通过 编程 的 方式 访问 GitHub API， 设 定 规则 之 后 便 能 收 到 工作 流程 中 特定 
事件 的 邮件 通知 。 用 户 关注 仓库 后 ， 有 人 提交 工 单 、 发 布 评论 、 发 起 拉 取 请 求 或 评论 提交 
时 ，GitHub 会 自动 发 送 通 知 邮件 。 此 外 ， 即 使 用 户 没有 关注 仓库 ， 当 被 提 到 (在 评论 中 使 
用 @ 加 用 户 名 的 方式 )、 被 分 配 工 单 或 者 参与 仓库 的 讨论 时 ， 也 会 收 到 通知 。 


GitHub 的 通知 策略 过 于 复杂 。 很 多 人 严重 依赖 电子 邮件 ,希望 所 有 重要 的 活动 都 能 传达 给 
正确 的 相关 人 。GitHub 的 通知 规则 丰富 ， 能 确保 把 正确 的 通知 传达 给 正确 的 人 。 


可 是 ， 电 子 邮 件 的 功能 已 经 弱化 ， 变 成 了 待 办 事项 清单 ， 而 且 ， 电 子 邮件 虽然 易 用 ， 但 是 
有 时 却 会 导致 一 个 问题 : 通知 被 淹没 。 不 停 地 切换 上 下 文 查看 邮件 时 特别 容易 走神 (构建 
软件 时 需要 极 高 的 注意 力 )， 这 样 容易 错过 通知 。 此 外 ， 电 子 邮件 是 针对 私人 的 ， 不 易 协 
作 ， 人 们 通常 不 会 共享 收 件 箱 中 的 邮件 。 下 面 ， 我 们 将 扩展 Hubot， 把 GitHub 通知 发 布 到 
共享 的 通信 频道 ， 让 用 户 登陆 后 可 以 选择 加 入 ， 以 此 来 解决 上 述 问题 。 
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8.4.1 编写 Hubot 扩 展 

Hubot 扩展 使 用 JavaScript 或 CoffeeScript 编写 。CoffeeScript 是 一 种 中 间 语 言 ， 直接 编 
译 成 JavaScript。 很 多 人 喜欢 使 用 CoffeeScript， 因 为 它 的 句法 更 简洁 ， 写 出 的 JavaScript 
更 安全 (CoffeeScript 句法 有 助 于 规避 JavaScript 语言 常见 的 隐蔽 陷阱 ， 例 如 this 引用 )。 
CoffeeScript 是 一 门 缩 进 式 语言 (类似 于 Python)， 入 门 之 后 ， 你 会 发 现 它 比 JavaScript 更 
易于 阅读 ， 髓 套 多 个 回调 函数 (JavaScript 编程 常见 的 做 法 ) 时 更 能 体现 这 一 点 ， 因 为 
通过 舱 套 等 级 能 轻易 区 分 国 数 的 首尾 。Hubot 是 使 用 CoffeeScript 编写 的 ， 我 们 也 将 使 用 
CoffeeScript 编写 扩展 。 








对 CoffeeScript 来 说 ， 缩 进 很 重要 。 为 了 提高 可 读 性 ， 显 示 从 长 文件 中 搞 取 
的 代码 片段 时 ， 我 们 会 修改 缩 进 竺 级， 去掉 原始 缩 进 。 如 果 复 制 时 没有 重新 
缩 排 ， 代 码 可 能 无 法 运行 ， 因 此 你 要 根据 上 下 文 重新 缩 排 。 
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Hubot 扩展 的 模块 机 制 十 分 简单 。Hubot 会 把 一 个 机 器 人 对 象 传 给 我 们 编写 的 JavaScript 模 
块 (使 用 export 句法 )， 把 众多 API 方法 提供 给 我 们 使 用 。 


扩展 Hubot 之 前 要 理解 几 个 概念 。scripts 目录 里 的 example.coffee 文件 中 有 针对 各 个 方法 
的 示例 。 























Hubot 有 个 “大 脑 ”。 这 是 内 部 状态 对 象 ， 在 不 同 的 聊天 消息 之 间 维 持 着 数据 。 状 态 默 
认 不 存 入 数据库 ， 因 此 重启 Hubot 之 后 状态 会 消失 。 不 过 ， 我 们 可 以 使 用 Redis 实现 持 
入 化 ， 但 这 是 可 选 的 ， 而 且 需 要 配置 。 大 脑 的 作用 是 供 我 们 设 定 或 者 获取 单个 消息 中 保 
存 的 值 。 

Hubot 有 不 同 的 啊 应 机 制 。 机 器 人 可 以 在 听 到 完全 一 致 的 词语 时 做 出 响应 ， 也 可 以 在 
发 现 消 息 中 包含 关键 词 时 做 出 啊 应 。 不 过 ， 我 们 不 用 在 代码 中 想方设法 区 分 这 两 种 通 
信 类 型 。 

Hubot 中 有 一 个 HTTP 服务 器 。 除 了 聊天 服务 之 外 ， 你 可 能 还 想 让 Hubot 处 理 其 他 服务 
的 请 求 ， 而 Hubot 能 轻松 处 理 这 些 请 求 。 

Hubot 内 置 了 HTTP 客户 端 。 在 Hubot 中 能 轻易 访问 HTTP 资源 ， 很 多 流行 的 Hubot 扩 
展 在 Hubot 收 到 请 求 时 会 访问 Web 服务 。 

Hubot 命令 可 以 包含 参数 。 我 们 可 以 编写 一 个 通用 函数 ， 通 过 参数 设 定 让 Hubot 多 次 执 
行 某 件 事 。 

Hubot 可 以 处 理事 件 。 各 个 聊天 服务 都 有 符合 标准 API 的 通用 事件 集 。 我 们 可 以 通过 编 
程 的 方式 让 Hubot 与 这 些 事件 交互 。 例 如 ， 变 换 话 题 或 用 户 离 开房 间 时 可 以 让 Hubot 执 
行 操作 。 
Hubot 可 以 处 理 常规 的 错误 。 我 们 可 以 在 代码 中 编写 一 个 捕获 全 部 错误 的 处 理 函 数 ， 这 
样 只 要 代码 出 错 我 们 就 可 以 捕获 ， 以 防 机 器 人 前 涡 。 































































































我 们 将 使 用 Hubot 的 前 五 个 功能 。 





使 用 Hubot 的 大 脑 存储 拉 取 请 求 的 审查 请 求 。 如 果 Hubot 邀请 某 个 用 户 审 查 拉 取 请 求 ， 
那么 必须 记 住 用 户 ， 这 样 当 用 户 反 馈 时 ，Hubot 才 有 关于 那 次 邀请 的 进一步 信息 。 
Hubot 发 出 审查 邀请 后 使 用 respond 方法 处 理 用 户 接受 或 拒绝 审查 请 求 。 

使 用 HTTP 服务 器 通过 GitHub 的 webhook 接收 拉 取 请 求 通知 。 

使 用 HTTP 客户 端 从 Slack 中 获取 用 户 列表 。 

使 用 发 给 Hubot 的 带 参 数 的 请 求 获取 聊天 消息 中 指明 的 拉 取 请 求 ID。 




















Hubot 的 源码 中 举例 说 明了 如 何 使 用 另外 两 个 功能 (事件 和 常规 错误 ) ， 不 过 我 们 的 Hubot 
不 会 用 到 这 些 API。 





8.4.2 ”通过 拉 取 请 求 审查 代码 
读 过 前 面 的 章节 可 知 ， 拉 取 请 求 是 GitHub 采用 的 一 种 机 制 ， 目 的 是 便于 把 代码 改动 集成 
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到 项 目 中 。 贡 献 者 可 以 派生 原 仓 库 ， 然 后 向 那个 仓库 发 起 拉 取 请 求 ， 或 者 ， 如 有 果 贡 献 者 有 
原 仓库 的 写 权 限 ， 还 可 以 创建 一 个 feature 分 支 ， 然 后 向 master 分 支 发 起 拉 取 请 求 。 











拉 取 请 求 经 常会 附带 一 个 消息 ， 指 明 让 哪些 人 审查 。 至 于 该 让 谁 审查 ， 只 有 创建 代码 的 开 
发 者 知道 。 页 献 者 可 能 邀请 了 正确 的 人 ， 也 可 能 基于 各 种 (完全 合理 的 ) 原因 ， 邀 请 他 们 
喜欢 的 人 审查 代码 。 这 或 许 是 让 正确 的 人 聚 在 一 起 审查 新 代码 的 有 效 方式 。 


可 是 ， 这 样 邀 请 审查 人 员 也 有 缺点 : 如 果 被 邀请 人 有 其 他 事 ， 没 有 看 到 通知 邮件 ， 拉 取 请 
求 可 能 长 期 无 人 问津 。 而 且 ， 根 据 一 项 研究 ， 平 均 分 配 任务 和 责任 的 团队 效率 最 高 。 通 
常 ， 让 所 有 人 都 参与 审查 拉 取 请 求 中 的 所 有 代码 效率 低下 。 相 反 ， 不 让 创建 代码 的 人 分 
配 ， 而 从 项 目 参与 者 中 随机 选择 一 个 开发 者 审查 代码 是 更 好 (效率 更 高 ) 的 一 种 方式 。 


出 现 新 的 拉 取 请 求 时 ，Hubot 会 要 求 聊 天 室 中 活跃 的 用 户 审查 代码 。 我 们 将 使 用 GitHub 
Activity API 订阅 拉 取 请 求 事件 。Hubot 发 现 有 拉 取 请 求 需要 审查 时 ， 会 从 聊天 室 中 随机 
选择 一 个 用 户 ， 询 癌 他 是 否 愿意 接受 挑战 。 如 果 用 户 接受 了 ， 我 们 将 在 拉 取 请 求 的 评论 中 
注 明 。 


1. 扩展 的 样板 代码 

编写 扩展 的 第 一 步 是 定义 期 望 从 用 户 那 里 接收 哪 种 高 级 通信 格式 。 我 们 的 目的 很 简单 : 寻 
找 表明 接受 或 拒绝 审查 邀请 的 回应 。 扩 展 脚 本 应 该 保存 在 scripts 目录 中 ， 我 们 将 其 命名 为 
pr-delegator.coffee。 这 只 是 我 们 与 用 户 之 间 的 交互 ， 处 理 拉 取 请 求 通知 的 代码 还 设 编写 。 





























































































































module.exports = (robot) -> @ 

robot .respond /accept/i, (res) -> 外 
accept( res ) 

robot .respond /decline/i, (res) -> © 
decLine( res ) 

accept = ( res ) -> @ 
res.reply "Thanks，you got it!" 
console.log "Accepted! "日 

decline = ( res ) -> @O 
res.reply "0K，I'LL find someone else" 
console.log "Declined!" 














代码 很 多 ， 刚 接触 CoffeeScript 的 人 可 能 不 解 其 意 。 读 过 下 述说 明之 后 ， 希 望 你 能 发 现 这 
短 短 一 段 代码 的 强大 之 处 。 


@ NodeJS 模块 的 开头 都 要 使 用 exports 句法 定义 入 口 点 。 这 行 代码 定义 一 个 接收 单个 参 
数 的 函数 。 执 行 这 个 函数 时 ， 参 数 名 为 robot。Hubot 框架 会 传人 一 个 robot 对 象 供 我 
们 使 用 。 

@ 使 用 Hubot API 在 robot 对 象 上 定义 的 respond 方法 。 这 个 方法 有 两 个 参数 : 用 于 匹配 
的 正则 表达 式 和 参数 为 聊天 响应 对 象 ( 这 里 的 res) 的 函数 。 后 一 行 把 响应 对 象 传 给 
accept 方法 。 我 们 稍 后 定义 accept 方法 。 
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@ 编写 函数 ， 处 理 decline 回应 。 

@ 这 里 定义 accept 方法。 这 个 方法 的 参数 是 Hubot 框架 生成 的 响应 对 象 ， 然 后 调用 
reply 方 法， 把 “Thanks, you got it!” 消 息 发 送 到 聊天 频道 中 (你 可 能 猜 到 了 )。 

日 然后 ，accept 方法 调用 console.1og 方 法， 把 消息 输出 到 启动 Hubot 的 控制 台中 。 这 是 
确认 一 切 正常 的 简单 方式 ， 如 果 没 看 到 这 个 消息 ， 说 明 在 此 之 前 的 代码 出 错 了 。 频 道 
中 的 任何 用 户 都 看 不 到 console.1log 输出 的 消息 。 确 定 生产 环境 使 用 的 代码 后 ， 最 好 把 
这 行 代码 删 掉 ， 不 过 ， 即 使 忘记 ， 也 不 会 对 频道 产生 任何 影响 。 

@ 然后 ， 使 用 与 accept 方法 同样 的 API 定义 decline 方法 。 


如 果 Hubot 正在 运行 中 ， 要 重启 才能 加 载 扩展 脚本 。 关 闭 Hubot ( 按 Ctrl-C 键 )， 重启， 然 
后 在 你 的 Slack 网 站 中 试 试 这 些 命令 。 输 入 probot accept 和 probot decline 命令 ， 你 会 
看 到 Hubot 在 频道 中 做 出 了 响应 。 此 外 ， 在 运行 Hubot 的 控制 台中 还 会 看 到 Accepted! 或 
Declined! 消息 。 
































2. 为 Hubot 扩 展 编写 测试 

现在 ， 我 们 的 Hubot 机 器 人 基本 运行 起 来 了 ， 下 面 要 编写 测试 ， 以 确认 代码 正确 。 我 们 将 
使 用 NodeJS 的 测试 框架 Jasmine。 这 个 框架 使 用 优雅 的 行为 驱动 测试 句法 ， 在 it 函数 的 
第 一 个 参数 中 指定 行为 ， 然 后 在 第 二 个 参数 中 定义 一 个 函数 ， 作 为 测试 运行 。Jasmine 负 
责 运行 各 个 it 函数 ， 运 行 结束 后 会 输出 细致 的 报告 ， 指 明 哪 些 测试 通过 了 ， 哪 些 测试 失败 
了 。Jasmine 测试 通常 使 用 JavaScript 编写 ， 不 过 最 新 版 Jasmine 还 支持 使 用 CoffeeScript。 
Hubot 是 使 用 CoffeeScript 编写 的 ， 那 么 我 们 也 使 用 CoffeeScript 编写 测试 。 测 试 要 放 在 
spec 目录 中 ， 而 且 文 件 名 要 以 .spec.coffee 结尾 。 假 设 测 试 文件 的 完整 文件 名 是 spec/pr- 
delegator.spec.coffee。Jasmine 期 望 测试 文件 的 文件 名 以 .spec 结尾 (后面 还 有 扩展 名 ，.js 
或 .coffee) ， 否 则 Jasmine 不 会 把 文件 识别 为 测试 。 




















Probot = require "../scripts/pr-delegator" 
Handler = require "../lib/handler" 


pr = undefined 
robot = undefined 


describe "#probot", -> 
beforeEach () -> 
robot = { 
respond: jasmine.createSpy( 'respond' ) 
router: { 
post: jasmine.createSpy( 'post' ) 
} 
} 


it "should verify our calls to respond", (done) -> 
pr = Probot robot 
expect( robot.respond.calls.count() ).toEqual( 2 ) 
done() 





测试 的 第 一 行 代码 把 那个 Hubot 扩展 模块 加 载 到 测试 脚本 中 ， 我 们 把 函数 的 返回 值 存在 
Probot 变量 中 。 然 后 ， 创 建 一 个 describe 函数 ， 把 相关 的 测试 组 织 在 一 起 。describe 函数 
的 参数 是 一 个 标识 符 (这 里 的 却 robot) 和 一 个 包含 多 个 让 调用 的 函数 。 此 外 ，describe 
国 数 中 还 可 以 定义 beforeEach 函数 ， 指 定 各 个 it 调用 的 通用 操作 。 这 里 ， 我 们 创建 一 个 
虚拟 的 robot 对 象 ， 传 给 后 面 的 Probot 函数 。 运 行 Hubot 时 ，Hubot 会 创建 robot 对 象 ， 
并 把 它 传 给 Probot 函数 ， 不 过 在 测试 中 ， 要 生成 虚拟 的 robot 对 象 ， 然 后 通过 方法 调用 
确认 它 的 配置 是 正确 的 。 如 果 修 改 了 Hubot 机 器 人 的 代码 ， 而 没有 更 新 测试 验证 改动 ， 那 
么 测试 会 失败 ， 从 而 得 知 需要 添加 测试 或 者 机 器 人 出 问题 了 。 有 自动 化 的 健全 性 检查 做 保 
障 ， 我 们 可 以 放心 地 编程 ， 让 Hubot 机 器 人 灵动 起 来 。 




















你 应 该 发 现 了 ， 测 试 也 在 robot 对 象 上 调用 了 几 个 方法 (robot.respond 和 robot.router. 
post)。 我 们 使 用 Jasmine 创建 “ 侦 件 ”(spy)， 然 后 生成 虚拟 国 数 ， 记 录 所 有 外 部 〈 生 
产 环 境 中 的 代码 或 者 测试 用 具 ) 交互 。 在 it 函数 中 ， 我 们 确认 的 确 调 用 了 那些 函数 。 我 
们 使 用 expect 函数 验证 在 robot 对 象 上 调用 了 两 次 respond 函数 ， 而 且 还 调用 了 robot. 
router .post 方法 。 





我 们 需要 安装 Jasmine， 方法 是 把 它 添加 到 package.json 文件 中 。 把 "jasmine-node": 
"^1.14.5" 添加 到 那个 文件 中 ， 记 得 要 在 前 一 行 末 尾 添加 逗号 。 添 加 的 代码 指定 Jasmine 版 
本 至 少 为 “1.14.5”。 














"hubot-shipit": "^0.1.1", 
"hubot-slack": "^3.2.1", 
"hubot-youtube": "^0.1.2", 
"jasmine-node": "^2.0.0" 


} 


3 
"engines": { 


执行 下 述 命令 ， 安 装 Jasmine 〈 库 本 身 和 测试 运行 程序 的 命令 行 工 具 ) ， 然 后 运行 测试 。 为 
了 节省 空间 ， 此 处 节 略 了 安装 命令 的 输出 。 





$ npm install 


hubot-slack@3.2.1 node_modules/hubot-slack 
[一 slack-client@1.2.2 (log@1.4.0, coffee-script@1.6.3, ws@0.4.31) 


$ ./node_modules/.bin/jasmine-node --coffee spec/ 


Finished in 0.009 seconds 
1 test, 1 assertions, 0 failures, 0 skipped 


测试 通过 了 ， 现 在 我 们 有 了 一 种 为 代码 编写 文档 以 及 验证 代码 是 否 符合 预期 的 方式 。 
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3. 设置 webhook 
现在 该 为 Hubot 机 器 人 添加 真正 的 功能 了 。 首 先 ， 需 要 注册 拉 取 请 求 事件 。 














这 个 操作 可 以 


在 GitHub 网 站 中 执行 ， 不 过 也 可 以 使 用 cURL 工具 在 命令 行 中 创建 webhook。 为 此 ， 我 们 





要 创建 身份 验证 令 牌 ， 然 后 使 用 令 牌 创建 webhook。 








执行 下 述 命令 创建 令 牌 ， 记 得 把 用 户 名 变量 的 值 (xrd) 替换 成 你 自己 的 。 














$ export USERNAME=xrd 
$ curl https://api.github.com/authorizations --user SUSERNAME --data 
'{"scopes":["repo"], "note": "Probot access to PRs" }' -X POST 





上 述 命令 可 能 有 三 种 响应 。 如 果 用 户 名 或 密码 错误 ， 会 得 到 如 下 所 示 的 错误 响应 。 


{ 
"message": "Bad credentials", 
"documentation_url": "https://developer .github.com/v3" 


} 


如 果 用 户 名 和 密码 正确 ， 而 且 没 有 启用 双重 身份 验证 ， 那 么 请 求 成 功 ， 
中 包含 一 个 令 牌 。 


{ 

"id": 238749874， 

"url": "https://api.github.com/authorizations/9876533", 

"app": { 
"name": "Probot access to PRs", 
"url": "https://developer .github.com/v3/o0auth_authorizations/",， 
"client _ id": "00000000000000000000" 

}， 

"token" : "fakedtoken1234" ， 

"hashed_token": "fakedhashedtoken7654", 





如 果 启 用 了 双重 身份 验证 ， 会 得 到 如 下 所 示 的 响应 消息 。 
{ 


"message": "Must specify two-factor authentication OTP code.", 
"documentation_url": 
"https://developer .github.com/v3/auth#working-with-two-factor-auth 


} 


返回 的 JSON 响应 


entication" 


执行 上 述 cURL 命令 后 得 到 的 如 果 是 这 个 消息 ， 你 会 通过 设 定 的 双重 身份 验证 途径 ( 短 











信 、Google Authenticator Oe a tl a 执 码 1 收 到 一 次 性 密码 。 
如 果 设 定 的 是 短信 途径 ， 查 看 短信 之 后 再 使 用 cURL 发 送 请 求 ， 这 一 次 要 添加 一 个 首部 。 





$ curl https://api.github.com/authorizations --user SUSERNAME --data 
'{"scopes":["repo"], "note": "Probot access to PRs" }' -X POST 
--header "X-GitHub-OTP: 423584" 

Enter host password for User 'xrd': 





这 几 步 操作 成 功 后 〈 不 管 有 没有 使 用 双重 身份 验证 ) ， 你 会 收 到 一 个 OAuth 令 牌 。 


{ 


} 


8.4. 





"id": 1234567， 

"url": "https://api.github.com/authorizations/1234567", 

"app": { 
"name": "Probot access to PRs (API)"， 
"url": "https://developer .github.com/v3/o0auth_authorizations/", 
"client_id": "00000000000000000000" 


}， 
"token": "ad5a36c3b7322c4ae8bb9069d4f20fdf2e454266" ， 
"note": "Probot access to PRs", 


"note_url": null, 
"created_at": "2015-01-13T06:23:532"， 
"updated_at": "2015-01-13T06:23:532"， 
"scopes": [ 

"notifications" 


] 


3 使 用 OAuth 令 牌 注册 事件 








现在 我 们 获得 了 用 于 创建 webhook 的 令 牌 。 执 行 下 述 cURL 命令 时 记得 要 使 用 正确 的 仓 


库 名 条 





0 访问 令 牌 。 此 外 ， 我 们 还 要 指定 推送 到 Heroku 之 后 获得 的 端点 (这 里 的 https:// 





inqry-chatbot.herokuapp.com), 


$ 
$ 
$ 
$ 


} 
$ 


REPOSITORY=testing_repostory 
TOKEN=ad5a36c3b7322c4ae8bb9069d4f20fdf2e454266 
WEBHOOK_URL=https://inqry-chatbot.herokuapp.com/pr 
CONFIG=$(echo '{ 
"name": "web", 
"active": true, 
"events": [ 
"push " ， 
"pull_request" 
]， 
"config": { 
"url": "'S$WEBHOOK_URL'", 
"content_type": "form", 
"secret" : "XYZABC" 
} 
') 
curl -H "Authorization: token S$TOKEN" \ 
H "Content-Type: application/json" -Xx POST \ 


-d "$CONFIG" https://api.github.com/repos/$USERNAME/S$REPOSITORY/hooks 


{ 


"url": "https://api.github.com/repos/xrd/testing_repostory/hooks/3846063", 
"test_url": 
"https://api.github.com/repos/xrd/testing_repostory/hooks/3846063/test", 
"ping_url": 
"https://api.github.com/repos/xrd/testing_repostory/hooks/3846063/pings", 
"id": 3846063， 
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"name": "web", 

"active": true, 

"events": [ 
"push " ， 
"pull_request" 


"config": { 
"url": "https://ingqry-chatbot.herokuapp.com/pr", 
"content_type": "json" 

}， 


"last_response": { 
"code": null, 
"status": "unused", 
"message": null 


}, 
"Updated _at": "2015-01-14T06:23:59Z"， 
"created_at": "2015-01-14T06:23:59Z" 


3} 


这 里 用 了 几 个 bash 技巧 ， 但 是 不 难 理解 。 我 们 创建 了 几 个 变量 ， 供 最 终 的 命令 使 用 。 因 
为 SCONFIG 变量 特别 长 ， 所 以 我 们 使 用 echo 把 中 间 带 有 webhook URL 的 一 堆 信息 打印 
出 来 了 。 如 果 想 查看 $CONFIG 变量 的 值 ， 输 入 echo $CONFIG6， 你 会 看 到 其 中 一 部 分 是 .…. 
"url": "https://inqry-chatbot.herokuapp.com/pr"” ...， 这 说 明 webhook 的 URL 正确 插 
入 了 。 















































这 里 使 用 Heroku API 的 URL 作为 webhook 的 端点 。 这 意味 着 要 在 Heroku 中 托管 应 用 ， 
webhook 才能 与 HTTP 服务 器 合理 交互 。 我 们 可 以 把 应 用 (比如 说 让 Hubot 连接 Slack 服 
务 ) 放 到 防火 墙 之 后 ， 让 该 应 用 与 聊天 室 成 员 交 互 ， 不 过 只 有 在 公开 可 访问 的 服务 器 中 运 
行 聊天 客户 端 ，webhook 才能 成 功 发 送 请 求 。 
































注意 ， 一 定 要 把 content_type 设 为 "form”( 这 是 默认 值 ， 可 以 留 空 )。 如 果 把 这 个 字段 设 
为 json， 那 么 很 难 从 Hubot 中 获取 原始 的 响应 主体 ， 因 为 接收 的 是 POST 请 求 ， 而 且 请 
求 会 使 用 安全 摘要 验证 。 我 们 要 保证 所 有 请 求 都 是 由 GitHub 发 出 的 ， 不 能 让 恶意 的 攻击 
者 参与 对 话 。 为 了 防止 发 生 这 样 的 事 ， 我 们 要 使 用 创建 webhook 时 生成 的 密令 验证 返回 
GitHub 的 各 个 请 求 。 本 章 后 面 会 深入 讨论 这 个 问题 ， 现 在 要 记 住 的 是 ， 创 建 webhook 时 
要 设 定 密 令 。 黑 客 可 能 会 猪 到 端点 的 地 址 ， 不 过 只 要 没有 攻破 Heroku 或 GitHub， 他 们 就 
不 知道 webhook 的 密令 。 









































我 们 要 更 新 测试 ， 确 保 覆 盖 这 个 新 功能 。 我 们 将 使 用 Hubot HTTP 服务 器 ， 即 Hubot 中 运 
行 的 内 置 Express 服务 器 。 新 添加 的 测试 应 该 验证 能 在 Hubot 机 器 人 上 调用 router ,post 方 
法 ， 而 且 已 调用 了 一 次 。 在 测试 文件 末尾 添加 下 述 测 试 。 











it "should verify our calls to router.post", (done) -> 
pr = Probot robot 
expect( robot.router.post ).toHaveBeenCalled() 
done() 





A 
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现在 运行 的 话 ， 新 添加 的 测试 会 失败 。 我 们 要 在 Hubot 机 器 人 中 添加 这 个 功能 ， 处 理 
GitHub 发 送 的 webhook 回调 。 在 文件 末尾 添加 下 述 代码 。 














robot.router.post '/pr', ( req, res ) -> 
console.log "We received a pull request" 


现在 运行 测试 ， 会 发 现 全 部 能 通过 。 通 过 后 ， 把 新 版 应 用 发 布 到 Heroku 中 。 以 后 我 们 会 
省 略 这 一 步 ， 不 过 要 想 在 设置 的 路 径 上 收 到 拉 取 请 求 ， 一 定 要 把 文件 发 布 到 Heroku 中 ， 
让 端点 可 以 公开 访问 。 





$ ./node_modules/.bin/jasmine-node --coffee spec/ 

$ git commit -m "Working tests and associated code" -a 
$ heroku push 

Finished in 0.009 seconds 

2 tests, 2 assertions, 0 failures, 0 skipped 

$ git push heroku master 

Fetching repository, done. 


Counting objects: 5, done. 
Delta compression using Up to 8 threads. 


至 此 ，Hubot 机 器 人 的 两 端 都 设置 好 了 ， 接 下 来 该 接收 webhook 发 送 的 通知 了 。 


8.4.4 发 起 真实 的 拉 取 请 求 
现在 可 以 使 用 真实 的 GitHub 通知 测试 这 个 Hubot 机 器 人 了 。 首 先 ， 创 建 用 于 测试 的 仓库 。 
使 用 第 6 章 介 绍 的 hub 工具 可 以 轻松 地 在 GitHub 中 新 建仓 库 。 














mkdir testing_repository 

cd testing_repository 

git init 

touch test.txt 

git add . 

git commit -m "Initial checkin 
hub create 


A 





接 下 来 ， 使 用 命令 行 工 具 为 仓库 创建 一 个 真实 的 拉 取 请 求 ， 然 后 测试 Hubot 机 器 人 。 创 建 
拉 取 请 求 的 常规 流程 如 下 : 


(1) 新 建 分 支 

(2) 添 加 新 内 容 

(3) 提交 内 容 

(4) 把 新 分 支 推送 到 GitHub 中 
(5) 发 起 拉 取 请 求 
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以 上 这 几 步 可 以 使 用 Git 命令 和 cURL 自动 执行 。 有 些 命令 之 前 用 过 ， 我 们 将 利用 前 面 使 
用 API 通过 cURL 创建 webhook 时 用 到 的 变量 。 配 置 变量 的 值 跟前 面 差不多 ， 不 过 所 需 的 
字段 不 同 ， 这 一 次 我 们 要 设 定 拉 取 请 求 的 标题 和 正文 ， 把 "head" 键 对 应 的 值 设 为 分 支 的 名 
称 ， 还 要 设置 "base" 键 ， 指 明 把 拉 取 请 求 合并 到 哪个 分 支 。 















































在 试验 和 学 习 Hubot 扩展 API 的 过 程 中 可 能 会 多 次 新 建 分 支 、 添 加 内 容 ， 再 发 起 拉 取 请 
求 。 这 里 给 出 的 示例 拿 来 就 能 用 ， 但 是 不 要 天 真 地 以 为 每 次 执行 的 效果 都 跟 第 一 次 一 样 。 
因为 在 试验 的 过 程 中 可 能 会 多 次 执行 这 些 命令 ， 所 以 我 们 把 执行 上 述 操 作 的 命令 写 和 一 个 
bash 脚本 ， 这 些 代码 是 通用 的 ， 可 以 多 次 运行 。 我 们 把 这 个 文件 命名 为 issue-pull-request. 
sh， 保 存在 test 目录 里 。 





# 请 修改 这 三 个 变量 
AUTH_TOKEN=b2ac1lf43aeb8d73b69754d2fe337de7035ec9df7 
USERNAME=xrd 

REPOSITORY=test_repository 


DATE=$(date "+%s") 

NEW_BRANCH=$DATE 

git checkout -b SNEN_BRANCH 

echo "Adding some content" >> test-S$DATE.txt 

git commit -m "Adding test file to test branch at $DATE" -a 
git push origin SNEN_BRANCH 

CONFIG=$(echo 

{ "title": "PR on '$DATE'", 


"body" : "Pull this PR'S$SDATE'", 
"head": "'S$NEW_BRANCH'", 
"base": "master" 


}') 
URL=https://api.github.com/repos/$USERNAME/S$REPOSITORY/pulls 
curl -H "Authorization: token SAUTH_TOKEN" \ 

-H "Content-Type: application/json" -X POST -d "$CONFIG" "S$URL" 








这 个 脚本 根据 当前 时 间 生 成 一 个 独一无二 的 字符 串 ， 然 后 以 这 个 字符 串 为 名 创建 并 检 入 新 
分 支 ， 再 把 一 些 内 容 添加 到 一 个 独一无二 的 文件 里 ， 提 交 之 后 推送 到 GitHub 中 ， 最 后 使 
用 API 生成 一 个 拉 取 请 求 。 你 只 需 把 脚本 顶部 的 三 个 变量 修改 为 自己 的 值 ， 而 且 只 需 修改 
一 次 。 这 个 脚本 的 适应 力 很 强 ， 如 果 身 份 验证 令 牌 是 错 的 (或 者 过 期 了 )， 那 么 它 只 会 把 
测试 数据 添加 到 测试 仓库 中 ， 因 此 可 以 放心 试验 。 不 过 ， 要 留意 JSON 响应 ， 看 请 求 成 功 
还 是 失败 ， 如 下 述 代码 片段 所 示 。 此 外 ， 因 为 我 们 要 把 这 个 脚本 当成 命令 使 用 ， 所 以 要 使 
用 chmod 命令 把 它 设 为 可 执行 文件 。 


现在 来 运行 这 个 脚本 ， 看 看 结果 如 何 : 

















$ chmod +x ./issue-pull-request.sh 
$ ./issue-pull-request.sh 





k 
"url": "https://api.github.com/repos/xrd/testing_repostory/pulls/1", 
"id": 27330198 ， 
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"htmL_urL" : "https://github.com/xrd/testing_repostory/pull/1", 

"diff_url": "https://github.com/xrd/testing_repostory/pull/1.diff", 
"patch_url": "https://github.com/xrd/testing_repostory/pull/1.patch", 
"issue_url": "https://api.github.com/repos/xrd/testing_repostory/issues/1", 


"number": 1， 

"state": "open", 

"locked": false, 

"title": "A PR test", 
"open_issyes count": 1， 


返回 的 JSON 响应 内 容 很 多 (这 里 做 了 市 略 )， 可 以 看 出 ， 第 一 个 字段 是 拉 取 请 求 的 链接 。 
不 过 ，html_url 字段 中 的 链接 才 是 人 类 可 读 的 。 访 问 这 个 链接 可 以 在 GitHub 的 网 页 UI 中 





合并 拉 取 请 求 。 





在 GitHub 中 查看 拉 取 请 求 之 后 ， 若 想 深 入 了 解 创建 拉 取 请 求 的 过 程 中 发 生 了 什么 ， 可 以 














打开 仓库 的 设置 页 面 ， 然 后 点 击 左 侧 导 航 栏 里 的 “Webhooks and Services”， 在 页 面 最 底部 
可 以 看 到 webhook 最 近 发 送 的 请 求 列 表 ， 如 图 8-7 所 示 。 








Recent Deliveries 


A ff27a200-9bb9-11e4-880e-ea8498645045 


A fdf67500-9bb9-11e4-88b5-b2eal5ac1123 


A ecab6980-9bb5-11e4-97aa-e10999147371 





2015-01-13 22:53:08。” 庄 守 


2015-01-13 22:53:06。 读 守 


2015-01-13 22:23:59 车 








图 8-7: webhook 最 近 发 送 失 败 的 请 求 


这 些 请 求 都 失败 了 ， 因 为 我 们 没有 正确 配置 Hubot 机 器 人 ， 让 它 处 理 GitHub 发 送 的 真实 
HTTP 请 求 。 不 过 ， 这 却 表明 GitHub 收 到 拉 取 请 求 时 确实 尝试 做 事 了 。 接 下 来 ， 我 们 将 编 
写 处 理 程序 的 代码 ， 把 新 代码 推送 到 Heroku 之 后 ， 再 发 起 拉 取 请 求 。 














8.4.5 通过 HTTP POST 请 求 处 理 拉 取 请 求 通知 














下 面 编写 HTTP 处 理 程 序 ， 人 处理 GitHub 发 来 的 拉 取 请 求 通知 。 起 初 ， 你 可 能 会 采取 简单 




















的 方式 ， 直 接 把 这 个 处 理 程序 添加 到 顶层 脚本 中 。 可 是 ， 考 虑 到 JavaScript 是 在 回调 中 处 
理事 件 的 ， 而 且 Hubot 扩展 只 导出 一 个 构造 方法 (使 用 module.exports 句法 ) ， 所 以 更 简 
单 也 更 易于 测试 的 方法 是 把 处 理 程序 写 入 单独 的 模块 ， 然 后 再 导入 扩展 的 主 脚 本 。 























首先 ， 编 写 测试 。 我 们 已 经 编写 了 一 个 测试 ， 验 证 了 robot.router.post 调用 。 了 既然 著 





功能 要 正式 处 理 拉 取 请 求 通知 ， 那 就 使 用 





"#pr"。 新 功能 很 简单 : 如果 Hubot 接收 到 


























describe 句法 添加 一 个 新 测试 组 ， 将 其 命名 为 
正确 的 参数 (最 重要 的 是 内 部 密令 要 与 请 求 发 
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送 的 密令 匹配 ) ， 那 就 把 拉 取 请 求 标 识 为 有 效 的 ， 然 后 在 聊天 室 中 发 布 进一步 指示 ， 即 邀 
请 某 个 用 户 审查 拉 取 请 求 。 这 个 功能 的 处 理 程序 要 导出 两 个 方法 ， 一 个 是 prhandter， 把 
HTTP 请 求 发 来 的 信息 转发 给 /pr 路 径 ， 另 一 个 是 setSecret， 用 于 配置 密令 。 规 划 好 处 理 
程序 的 内 部 签名 之 后 ， 我 们 先 添 加 两 个 简单 的 测试 ， 然 后 再 实现 处 理 程序 。 


我 们 要 编写 两 个 测试 ， 一 个 处 理 正确 的 流程 ， 另 一 个 处 理 错误 的 流程 。 我 们 将 在 
beforeEach 块 (在 每 个 测试 之 前 都 要 运行 ) 中 创建 一 个 虚拟 的 robot 对 象 ， 并 为 处 理 程序 
模块 设置 密令 。 虚 拟 的 robot 对 象 实现 的 方法 (messageRoom 和 send) 要 与 Hubot 提供 的 
真实 的 robot 对 象 一 样 ， 不 过 这 里 将 使 用 Jasmine 创建 侦 件 ， 验 证 实现 代码 有 没有 调用 这 
两 个 方法 。 
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describe "#pr", -> 
secret = "ABCDEF" 
robot = undefined 
res = undefined 


beforeEach -> 
robot = { 
messageRoom: jasmine.createSpy() 
} 
res = { send: jasmine.createSpy() } 
Handler.setSecret secret 


it "should disallow calls without the secret", (done) -> 
req = {} 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).not.toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


t "should allow calls with the secret", (done) -> 
req = { body: { secret: secret } } 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


然后 ， 新 建 ./lib/handler.coffee 文件 ， 写 入 : 





_SECRET = undefined 


exports.prHandler = ( robot, req, res ) -> 
secret = req.body?.secret 
if secret == _SECRET 
console.log "Secret verified, let's notify our channel" 
room = "general" 
robot.messageRoom room, "OMG, GitHub is on my caller-id!?!" 
res.send "OK\n" 


exports.setSecret = (secret) -> 
_SECRET = secret 





可 以 看 出 ，Hubot API 为 我 们 做 了 很 多 事情 ， 它 会 处 理发 往 /pr 端点 的 JSON 格式 POST 请 
求 ， 把 解析 得 到 的 参数 保存 到 body 对 象 中 。 我 们 就 使 用 这 个 对 象 获取 请 求 中 的 密令 。 即 
使 你 以 前 用 过 CoffeeScript， 可 能 也 不 熟悉 ?. 句法 。 那 行 代码 的 作用 是 ， 测 试 body 是 否 存 
在 ， 如 果 存 在 ， 那 么 获取 其 中 的 secret 键 。 这 样 一 来 ， 即 使 请 求 没 有 发 送 密令 ， 程 序 也 
不 会 月 涡 。 如 果 请 求 发 送 的 密令 与 配置 的 密令 一 样 ， 那 么 在 聊天 室 中 发 布 一 条 消息 ， 否 则 
就 忽略 请 求 。 不 管 哪 种 情况 ， 都 要 使 用 send 方法 (由 Hubot 用 来 提供 HTTP 服务 器 的 内 
部 Express 服务 器 提供 ) 把 响应 发 给 服务 器 。 为 了 调试 ， 当 密令 有 效 时 我 们 输出 一 个 消息 ， 
如 果 不 这 么 做 ， 不管 客 户 端 有 没有 提供 密令 ， 响 应 都 是 一 样 的 ， 不 易于 区 分 。 如 果 攻 击 者 
传 入 的 密令 不 对 ， 我 们 不 能 为 他 提供 任何 额外 的 信息 。 









































现在 运行 测试 ， 会 发 现 全 部 能 通过 。 


$ node_modules/jasmine-node/bin/jasmine-node \ 
--Coffee spec/pr-delegator.spec.coffee 


Finished in 0.01 seconds 
4 tests, 6 assertions, 0 failures, 0 skipped 


不 管 在 哪儿 运行 Hubot， 它 都 能 派生 HTTP 服务 器 ， 因 此 在 本 地 设备 中 运行 时 也 能 与 之 通 
信 (不 过 ， 本 地 运行 的 Hubot 可 能 在 防火 墙 后 面 ， 无 法 访问 GitHub) ， 于 是 我 们 可 以 在 本 
地 使 用 cURL 测试 。 广 意 ， 机 器 人 的 /pr 端点 接收 的 是 HTTP POST 请 求 ， 因 此 我 们 要 发 
送 POST 请 求 (在 cURL 中 使 用 - -data 开关 ) 。 





























$ ( HUBOT_SLACK_TOKEN=xoxb-3295776784-nZxL1H3nyLsVcgdD29r1PZCq \ 
./bin/hubot -a slack 2> /dev/null | grep -i secret & ) 

$ curl --data '' http://LocaLhost:8080/pr 

Invalid secret 

OK 

$ curl --data 'secret=XYZABC' http://localhost:8080/pr 

Secret verified 

OK 

$ kill ‘ps a | grep node | grep -v grep | awk -F ' ' '{ print $1 }' 


上 述 命令 证 实 运 作 正 常 。 首 先 ， 启 动 服务 器 ， 通 过 管道 把 输出 传 给 grep 命令 ， 输 出 与 密 
令 相关 的 信息 (使 用 8 符号 和 括号 把 整个 命令 链 放 在 后 台 运 行 ， 这 是 一 个 bash 技巧 )。 然 
后 ， 请 求 本 地 服务 器 ， 我 们 没有 发 送 密令 ， 因 此 服务 器 〈 运 行 在 同一 个 shell 中 ) 调用 
console.1og 方法 打印 出 “Invalid secret” 消 息 ; 随后 ，cURL 打印 出 “OK”， 这 是 服务 器 
返回 的 响应 。 然 后 ， 再 次 执行 cURL 命令 ， 不 过 这 一 次 在 POST 参数 中 发 送 了 密令 。 可 以 
看 出 ，Hubot 确认 传 入 的 密令 与 内 部 保存 的 密令 一 样 ， 随 后 cURL 再 次 打印 出 “OK”， 这 
是 Hubot 中 Express 服务 器 返回 给 客户 端的 响应 。 最 后 一 行 关闭 Hubot: 先 找到 Hubot 客 
户 端 (NodeJS 进程 ) 的 PID， 然 后 向 其 发 送 SIGHUP 信号 ， 关 闭 Hubot。 






































如 果 正 确 连 接 了 Slack 网 站 ， 还 会 在 #eeneral 频道 中 看 到 一 个 消息 ， 即 “OMG, GitHub is 
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on my caller-id!1?!1”。 至 此 ， 我 们 无 需 手 动 操 作 就 能 发 出 拉 取 请 求 通知 了 。 脚 本 用 于 通过 
GitHub API 发 起 真实 的 拉 取 请 求 ， 而 虚拟 的 webhook 通知 则 用 于 在 开发 过 程 中 从 外 部 测试 
脚本 中 的 代码 。 测 试 诚然 有 其 作用 ,但 是 只 使 用 测试 用 具 做 测试 而 不 真正 运行 Hubot， 那 
就 无 法 理解 Hubot 内 部 的 运作 过 程 。 

1. 分 配给 聊天 室 中 某 个 活跃 的 用 户 

现在 拉 取 请 求 通知 有 了 (尽管 是 我 们 虚拟 的 )， 接 下 来 要 编写 代码 ， 随 机 选择 一 个 用 户 ， 
让 他 审查 拉 取 请 求 。 














这 一 节 是 多 余 的 ， 即 使 把 这 一 节 添 加 的 代码 都 删 掉 ， 我 们 的 Hubot 机 器 人 也 
完全 能 正常 运作 。 撰 写本 书 的 过 程 中 ， 我 没 意 识 到 Hubot 的 大 脑 中 存储 着 用 
户 列 表 ， 却 使 用 其 他 方式 (Slack API) 获取 这 些 数据 。 使 用 Slack API 写 完 
本 章 后 ， 我 才 发 现 自己 错 了 。 








起 初 ， 我 计划 把 这 一 节 删 掉 。 可 是 ， 这 一 节 却 演示 了 如 何 使 用 内 置 的 HTTP 
客户 端 访问 外 部 服务 ， 这 是 Hubot 的 一 个 强大 功能 ， 用 法 很 简单 。 此 外 ， 
这 一 节 还 演示 了 如 何 使 用 强大 的 测试 协助 开发 Hubot 扩展 。 有 了 测试 ， 我 
可 以 重 构 代 码 ， 使 用 完全 不 同 的 方式 获取 用 户 列表 ， 而 且 能 确保 新 代码 的 
处 理 方式 是 正确 的 。 此 外 ，Slack API 为 登录 聊天 室 的 用 户 提 供 了 更 为 丰富 
的 数据 ， 虽 然 这 一 市 用 不 到 ， 但 是 在 别 的 场景 下 却 很 有 用 。 如 果 跳 过 本 方 ， 
使 用 前 面 的 编写 的 代码 也 行 ， 不 过 我 觉得 为 了 更 好 地 理解 Hubot， 本 节 还 
是 值得 一 读 的 。 
































为 了 查找 聊天 室 里 的 用 户 ， 可 以 跳出 Hubot API， 使 用 Slack API 查询 用 户 列表 。Slack API 
的 一 个 端点 能 返回 当前 在 聊天 室 中 的 全 部 用 户 。 我 们 将 使 用 Hubot 内 置 的 HTTP 客户 端 访 
问 Slack API。 获 得 用 户 列 表 之 后 ， 可 以 随机 从 中 选择 一 个 ， 衣 请 他 审查 拉 取 请 求 。 





_SECRET = undefined 


anyoneButProbot = (members) -> @ 
user = undefined 
while not user 
user = members[ parseInt( Math.random() * \ 
members.Length ) ].name 
user = undefined if "probot" == User 
user 


sendPrRequest = ( robot, body, room, url ) -> © 
parsed = JSON.parse( body ) 
User = anyoneButProbot( parsed.members ) 
robot.messageRoom room, "#{user}: Hey, want a PR? #{url}" 


exports.prHandler = ( robot, req, res ) -> 
slack_users url = ©@ 
"https://slack.com/api/users.list?token=" + 





process.env.HUBOT_SLACK_TOKEN 
secret = req.body?.secret @ 
url = req.body?.url 


if secret == _SECRET and url 

room = "general" 

robot.http( slack_users url ) 日 

.get() (err, response, body) -> 
sendPrRequest( robot, body, \ 
room, url ) unless err 

else 

console.log "Invalid secret or no URL specified" 
res.send "OK\n" 


exports.setSecret = (secret) -> 
_SECRET = secret 











@ 定义 一 个 名 为 anyoneButProbot 的 方法 ， 其 参数 是 用 户 列 表 ， 作 用 是 从 中 随机 选择 一 个 
用 户 ， 只 要 不 是 Hubot 本 身 即 可 。 

@ sendPrRequest 方法 解析 Slack API 返 回 的 JSON， 把 对 象 里 的 用 户 列 表 传 给 
anyoneButProbot 方法 调用 。 然 后 ， 使 用 Hubot API 在 聊天 室 中 发 布 一 条 消息 ， 询 问 那 
个 选中 的 用 户 是 否 接受 拉 取 请 求 审 查 邀 请 。 

@ 把 Slack API 的 令 牌 添加 到 Slack API 的 基 URL 后 面 ， 构 成 请 求 Slack 服务 的 URL。 

跟 之 前 一 样 ， 读 取 密 令 和 拉 取 请 求 的 URL， 确 保 二 者 都 存在 。 

@ 使 用 内 置 的 HITP 客户 端 向 Slack API 发 起 GET 请 求 。 如 果 收 到 的 不 是 错误 响应 ， 那 
么 使 用 Slack API 提供 的 数据 开始 处 理 拉 取 请 求 审查 邀请 。 


可 以 使 用 cURL 命令 测试 ， 不 过 要 稍微 修改 一 下 : 














© 























$ curl --data 'secret=XYZABC&urL=http://pr/1' \ 
http://localhost:8080/pr 


随机 选中 的 用 户 会 看 到 这 条 消息 : username: Hey，want a PR? http://pr/1 (Slack 客户 端 
会 把 URL 格式 化 成 可 点 击 的 链接 )。 





然而 ， 测 试 失 败 ， 得 到 这 个 错误 : TypeError: 0bject #<0bject> has no method 'http'。 
这 是 因为 我 们 在 测试 中 模拟 的 robot 对 象 没有 Hubot 内 置 的 HTTP 接口 ， 因 此 我 们 要 将 其 
添加 到 模拟 的 机 器 人 对 象 中 。HTTP 客户 端 (由 node-scoped-http-client 包 提 供 ) 的 方法 
签名 很 复杂 : 要 把 几 个 方法 串联 起 来 构成 HTTP 客户 端 请 求 ， 然 后 把 一 个 回调 传 给 返回 的 
国 数 ， 处 理 响应 主体 。 使 用 这 个 模块 写 出 的 代码 不 易于 测试 〈 换 句 话 说， 我 要 想方设法 弄 
清楚 在 测试 中 该 怎么 模拟 ) ， 不 过 幸好 有 示例 代码 ， 以 及 说 明 机 器 人 接口 的 测试 ， 我 这 才 
理解 了 。 我 们 模拟 这 个 方法 链 ， 为 模拟 的 robot 对 象 定义 http 属性 。 这 个 属性 本 身 也 是 国 
数 ， 调 用 后 返回 一 个 带 有 get 方法 的 对 象 ， 而 调用 get 方法 返回 一 个 三 参数 回调 函数 。 这 
个 回调 函数 中 包含 错误 代码 、 响 应 对 象 和 JSON， 但 是 在 这 里 ， 只 要 错误 代码 是 空 的 ， 我 
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们 就 解析 JSON ， 获 取 用 户 列表 ， 然 后 发 出 拉 取 请 求 审查 邀请 。 


json = '{ "members" : [ { "name" : "bar"” } , { "name"” :; "foo" } ] }' 


httpSpy = jasmine.createSpy( 'http' ).and.returnVaLue( 
{ get: () -> ( func ) -> 


func( undefined, undefined, json ) } ) 


beforeEach -> 
robot = { 
messageRoom: jasmine.createSpy( 'messageRoom' ) 
http: httpSpy 
} 
res = { send: jasmine.createSpy( 'send' ) } 


Handler .setSecret secret 


it "should disallow calls without the secret", (done) -> 
req = {} 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).not.toHaveBeenCalled() 
expect( httpSpy ).not.toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


it "should disallow calls without the url", (done) -> 
req = { body: { secret: secret } } 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).not.toHaveBeenCalled() 
expect( httpSpy ).not.toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


it "should allow calls with the secret", (done) -> 
req = { body: { secret: secret, url: "http://pr/1" } } 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).toHaveBeenCalled() 
expect( httpSpy ).toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


上 述 测试 代码 能 写 出 来 真是 不 容易 ， 我 重 构 了 多 次 ， 确 保 测 试 和 代码 都 易于 阅读 。 编 写 测 
试 要 投入 很 多 精力 ， 不 过 测试 和 代码 都 易于 阅读 而 且 简 洁 的 话 ， 通 常 可 以 确定 实现 方式 是 


对 的 。 





至 此 ， 我 们 实现 了 完整 可 用 的 代码 ， 这 些 代 码 先 获 取 用 户 列 表 ， 然 后 随机 从 中 选择 一 个 用 
户 ， 邀 请 他 审查 拉 取 请 求 。 


2. 从 Hubot 的 大 脑 中 获取 用 户 列表 
我 们 可 以 不 用 Slack API， 而 是 调用 一 个 简单 很 多 的 方法 : robot.brain.users。 调 用 Slack 


























用 户 API 要 处 到 








回 








调 ， 而 brain.users 方法 不 需要 ， 写 出 的 代码 更 简洁 。 前 面 编 写 的 测试 





大 
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在 Jasmine 创建 的 HITP 侦 件 上 调用 了 get 方法 ， 我 们 要 把 那 部 分 删 掉 。 然 后 ， 为 虚拟 的 
Hubot 机 器 人 的 大 脑 (brain) 提供 一 个 新 函数 ， 即 users。 


这 样 : 





可 是 ， 不 能 把 代码 改 成 下 











Users = robot.brain.users() 
sendPrRequest( robot, users, room, url, number ) 





你 可 能 以 为 Slack API 返回 的 用 户 列 表 与 Hubot 机 器 人 大 脑 里 存储 的 用 户 列 表 是 一 样 的 ， 
甚 实 二 者 的 结构 差别 很 大 。 那 么 ， 我 们 怎么 确定 新 的 结构 呢 ? NodeJS 的 标准 库 中 有 个 名 
为 util 的 模块 ， 从 名 称 中 可 以 得 知 ， 这 个 模块 提供 了 很 多 实用 的 函数 。 其 中 一 个 实用 函数 
是 inspect， 其 作用 是 深入 对 象 ， 以 精美 的 格式 把 对 象 的 结构 打印 出 来 。 我 们 可 以 使 用 这 
个 函数 和 console.1log 查看 传 给 accept 函数 的 响应 对 象 ， 全 面 了 解 里 面 的 内 容 。console. 
log( require( 'util' ).inspect( users ) ) 这 行 代码 输出 的 内 容 如 下 所 示 。 









































{ U04FVFE97: 
{ id: 'UQ4FVFE97', 
name: 'ben’', 
real_name: 'Ben Straub', 
email_address: 'xxx' }, 
U038PNUP2 : 
{ id: 'U038PNUP2 ' ， 
name: 'probot', 
real_name: ''， 
email_address: undefined }, 
U04624M1A: 
{ id: 'U04624M1A ' ， 
name: 'teddyhyde', 
real_name: 'Teddy Hyde ' ， 
emaiL address: 'xxx' }, 
U030YNMBJY : 
{ id: 'U030YMBJY ' ， 
name: 'xrd', 
real_name: 'Chris Dawson ' ， 
emaiL address: 'xxx' }, 
USLACKBOT: 
{ id: 'USLACKBOT', 
name: 'slackbot', 
real_name: 'Slack Bot', 
email_address: null } } 




















咽 ， 确 实 如 此 ，Slack API 返回 的 是 数组 ， 而 这 是 关联 数组 (在 其 他 语言 中 叫 hash)。 因 此 ， 
我 们 要 重 构 济 试 中 输入 的 数据 ， 把 数组 改 成 关联 数组 ， 然 后 使 用 一 个 函数 将 其 打 平 (这 以 
后 的 代码 与 前 面 一 样 了 )。 该 关联 数组 在 调用 robot.brain.users 函数 时 返回 ， 因 此 我 们 要 
在 虚拟 的 robot 对 象 中 增加 一 个 侦 件 ， 放 在 users 键 上 。 
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Users = { CDAWSON: { name: "Chris Dawson" }, BSTRAUB: { name: "Ben Straub" } } 
bratinSpy = { 

Users: jasmine.createSpy( 'getUsers' ).and.returnValue( users )， 

set: jasmine.createSpy( 'setBrain' )， 


在 实现 代码 中 ， 要 打 平 用 户 关联 数组 ， 然 后 在 打 平 后 的 数组 中 查找 用 户 。 





flattenUsers = (users) -> 
rv = [] 
for x in Object.keys( users ) 
rv.push users[x] 
rv 


anyoneButProbot = ( Users ) -> 
user = undefined 
flattened = flattenUsers( users ) 
while not user 
user = flattened[ parseInt( Math.random() * \ 
flattened. length ) ].name 
user = undefined if "probot" == User 
user 


3. 通过 webhook 发 送 拉 取 请 求 数 据 

集成 就 要 完成 了 ， 接 下 来 要 发 送 真 实 的 拉 取 请 求 信 息 。 如 果 运 行 issue-pull-request.sh 
脚本 ， 会 发 现 它 把 数据 发 送 给 我 们 的 Hubot 机 器 人 。 部 署 到 Heroku 之 后 ， 我 们 的 Hubot 
机 器 人 在 公开 的 主机 名 上 监听 。 收 到 拉 取 请 求 后 ，GitHub 会 向 Hubot 机 器 人 发 送 POST 请 
求 ， 并 在 请 求 主体 中 发 送 JSON 数据 。 这 些 数据 与 cURL 脚本 中 使 用 的 URL 编码 参数 差别 
很 大 ， 因 此 要 修改 代码 。 


POST 请 求 发 送 的 JSON 数据 如 下 所 示 (为 了 简洁 明了 ， 我 重新 编排 了 格式 ) 。 


























{ 

"action": "opened", 

"number" :13， 

"pull_request": { 
"locked" : false, 
"comments_url" : 
"https://api.github.com/repos/xrd/test_repository/issues/13/comments", 
"url" : "https://api.github.com/repos/xrd/test_repository/pulls/13", 
"htmL_urL" : "https://github.com/xrd/test_repository/pulls/13", 
} 


} 











其 中 最 重要 的 是 一 个 URL (更 确切 地 说 是 htmL_urt) ， 我 们 的 Hubot 机 器 人 将 在 消息 中 把 


>™ 


它 发 给 用 户 。 在 Hubot 机 器 人 中 获取 并 解析 这 些 JSON 数据 的 方法 很 简单 。 
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exports.prHandler = ( robot, req, res ) -> 
body = req.body 
pr = JSON.parse body if body 
url = pr.pull_request.html_url if pr 
secret = pr.secret if pr 


if secret == _SECRET and url 
room = "general" 


在 上 述 代码 中 ， 我 们 从 响应 中 读 取 主体 内 容 ， 然 后 按照 JSON 格式 解析 ， 再 从 解析 后 
JSON 数据 中 提取 密令 和 那个 URL， 然 后 像 之 前 一 样 继续 处 理 。 








测试 也 很 简单 ， 而 且 要 传人 JSON 数据 。 


it "should disallow calls without the secret and url", (done) -> 
req = {} 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).not.toHaveBeenCalled() 
expect( httpSpy ).not.toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


t "should allow calls with the secret and url", (done) -> 
req = { body: '{ "pull_request" : { "html_url"” : "http://pr/1" }, 
"secret": "ABCDEF" }' } 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).toHaveBeenCalled() 
expect( httpSpy ).toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


方便 起 见 ， 我 们 直接 在 JSON 数据 中 指定 密令 。GitHub 通过 webhook 发 给 我 们 的 JSON 数 
据 中 没有 密令 ~ ， 这 这 么 做 只 是 为 了 简便 。 现在 运行 测试 ， 全 部 都 能 通 站 过 


4. 保卫 webhook 

现在 ， 如 果 发 送 的 密令 正确 ， 而 且 webhook 发 送 的 数据 正确 ， 那 么 我 们 的 Hubot 机 器 人 
就 能 正常 运作 。 接 下 来 ， 我 们 要 保卫 webhook。GitHub 会 对 webhook 载荷 中 的 数据 签名 ， 
从 而 确认 数据 的 确 发 自 经 认可 的 主机 。 因 此 ， 我 们 要 在 处 理 程序 中 解码 数据 。 于 是 ， 我 们 
要 获取 GitHub 在 请 求 首 部 中 发 送 的 安全 散 列 值 。 然 后 ， 使 用 内 部 存储 的 密令 计算 散 列 值 ， 
如 果 与 首部 中 的 散 列 值 一 致 ， 说 明 入 站 请 求 和 JSON 数据 确实 由 GitHub 发 送 ， 而 不 是 由 攻 
































getSecureHash = (body, secret) -> 
hash = crypto. 
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createHmac( 'sha1' ，secret ). 
update( "sha1=" + body ). 
digest('hex ' ) 

ConsoLe.Log "Hash: #{hash}" 

hash 


exports.prHandler = ( robot, req, res ) -> 

slack_users_url = 
"https://slack.com/api/users.list?token=" + 
process.env.HUBOT_SLACK_TOKEN 

body = req.body 

pr = JSON.parse body if body 

url = pr.pull_request.html_url if pr 

secureHash = getSecureHash( body, _SECRET ) if body 

webhookProvidedHash = req.headers['HTTP_X_HUB_SIGNATURE' ] \ 

if req?.headers 
secureCompare = require "secure-Compare' 


if secureCompare( secureHash, webhookProvidedHash ) and url 
room = "general" 
robot.http( slack_users_url ) -> 
.get() (err, response, body) -> 
sendPrRequest( robot, body, \ 
room, url ) unless err 
else 


GitHub 所 做 的 签名 是 基于 散 列 济 数 的 报 文 验证 码 (Hash Message Authentication Code， 
HMAC)， 这 种 加 密 方式 容易 受到 时 序 攻 击 : 在 对 比 计 算 的 散 列 值 和 收 到 的 散 列 值 的 过 
程 中 ， 攻 击 者 可 以 暴力 获取 服务 器 的 访问 权 。 具 体 到 JavaScript， 宽 松 的 比较 运算 符 (如 
==) 就 会 泄露 时 序 信息 。 为 了 防止 泄露 时 序 信 息 ， 被 人 用 来 入侵 主机 系统 ， 我 们 要 使 用 
secure-compare 模块 ， 在 比较 散 列 值 时 隐藏 时 序 信息 。 为 了 加 载 这 个 模块 ， 要 把 它 添加 到 
清单 文件 package.json 中 ， 然 后 执行 npm install secure-compare --save 命令 。 






































然后 ， 根 据 处 理 函 数 的 这 个 新 关注 点 调整 测试 。 


it "should disallow calls Without the secret and url", (done) -> 
req = {} 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).not.toHaveBeenCalled() 
expect( httpSpy ).not.toHaveBeenCalled() 
expect( res.send ).toHaveBeenCalled() 
done() 


t "should allow calls with the secret and url", (done) -> 
req = { body: '{ "pull_request" : { "html_url"” : "http://pr/1" }}', 
headers: { "HTTP_X_HUB_SIGNATURE" : 
"cd970490d83c01b678fa9af55f3c7854b5d22918" } } 
Handler .prHandler( robot, req, res ) 
expect( robot.messageRoom ).toHaveBeenCalled() 
expect( httpSpy ).toHaveBeenCalled() 
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expect( res.send ).toHaveBeenCalled() 
done() 


可 以 看 出 ， 我 们 把 密令 从 JSON 数据 中 移 除 ， 放 到 首部 中 去 。GitHub 的 webhook 会 编码 
JSON 数据 ， 并 在 HTTP_X_HUB_SIGNATURE 键 中 发 送 安全 散 列 值 ， 因 此 我 们 的 Hubot 机 器 人 
接收 到 的 也 是 这 种 结构 。 测 试 中 要 在 模拟 的 请 求 对 象 中 提供 同样 的 签名 。 可 以 把 处 理 函 数 
中 生成 安全 散 列 值 的 代码 复制 到 测试 中 ， 不 过 也 可 以 偷懒 ， 先 运行 测试 (知道 这 一 次 会 失 
败 )， 找 到 console.1log 输出 的 “Hash: cd970490d83c…”， 把 它 复 制 到 模拟 的 请 求 对 象 中 。 
这 样 做 之 后 ， 测 试 就 能 通过 了 。 
































现在 ， 重 新 加 载 Hubot 机 器 人 ， 然 后 使 用 issue-pull-request.sh 脚本 发 起 拉 取 请 求 。 此 
时 ， 本 该 看 到 一 致 的 散 列 值 ， 但 是 却 没 有 (至少 使 用 前 述 的 package.json 文件 时 是 这 样 )， 
这 是 因为 写作 本 书 时 ，Hubot 有 个 严重 的 缺陷 。 








前 面 说 过 ，Hubot 附带 了 NodeJS 平台 的 一 个 高 性 能 Web 框架 Express.js。 这 个 框架 采用 模 
块 化 架构 ， 在 请 求 和 响应 之 间 揪 入 了 中 间 件 。 采 用 这 种 方式 构建 功能 ， 加 上 数量 众多 的 中 
间 件 ，Web 开发 者 可 以 根据 手头 要 解决 的 问题 ， 把 所 需 的 标准 化 中 间 件 组 件 串 联 起 来 。 常 
用 的 中 间 件 有 静态 文件 中 间 件 〈 用 于 伺服 静态 文件 )、cookie 中 间 件 、 会 话 中 间 件 和 主体 
解析 中 间 件 。 可 以 想象 ， 这 些 中 间 件 并 不 是 始终 都 需要 (可 能 还 需要 其 他 的 ) 。Express.js 
的 这 种 灵活 性 使 得 它 成 为 构建 NodeJS Web 应 用 的 首选 。 


这 里 ， 我 们 特别 关注 主体 解析 中 间 件 ， 使 用 它 把 请 求 的 主体 转换 成 JavaScript 对 象 ， 然 
后 依附 到 请 求 对 象 上 。 前 面 我 们 在 回调 中 使 用 req 变量 访问 请 求 对 象 ， 显 然 这 个 名 称 是 
request 的 简写 。 主 体 解析 中 间 件 能 把 HTTP 请 求 中 的 任何 数据 转换 成 符合 JavaScript 结构 
要 求 的 关联 数组 ， 并 将 其 存储 在 request 对 象 中 的 body 对 象 中 。 如 果 主 体 是 编码 的 URL 
(如 果 创 建 webhook 时 把 content_type 设 为 form， 拉 取 请 求 信息 会 被 编码 )， 主 体 解 析 中 
间 件 会 解码 内 容 ， 把 它 当 作 JSON 数据 解析 ， 然 后 把 得 到 的 对 象 存 储 在 request 对 象 的 
body 属性 中 。 通 常 ， 这 个 过 程 能 省 去 Web 应 用 开发 者 的 大 量 繁重 工作 。 






























































可 惜 ， 附 带 的 express 对 象 在 加 载 扩 展 之 前 就 已 经 配置 好 了 ， 我 们 不 能 打破 加 载 顺 序 ， 无 
法 插入 主体 解析 中 间 件 ， 因 此 无 法 获取 原始 的 主体 内 容 。 主 体 解 析 中 间 件 处 理 数据 流 的 
方法 是 ， 为 HTTP 请 求 流 中 的 事件 注册 回调 。NodeJS 之 所 以 能 在 Web 应 用 领域 占据 一 
席 之 地 ， 是 因为 它 提供 的 网 络 应 用 工具 包 大 量 使 用 JavaScript 最 具 争 议 的 一 个 特性 : 异步 
回调 。 在 NodeJS 中 ， 进 程 注册 事件 之 后 会 把 控制 权 交 还 宿主 程序 。 在 其 他 语言 中 ， 例 如 
Ruby， 如 果 服 务 要 接收 客户 端 发 送 的 数据 ， 默 认 情 况 下 要 监听 入 站 数据 ， 可 是 ， 让 程序 
监听 时 ， 其 他 过 程 就 阻塞 了。 异步 编程 并 不 是 什么 新 概念 (例如 很 多 语言 都 支持 多 线程 )， 
但 是 NodeJS 通过 事件 注册 机 制 简 化 了 与 异步 函数 交互 的 方式 。 然 而 ， 对 Express.js 的 中 间 
件 来 说 ， 这 个 事件 注册 过 程 却 妨碍 了 我 们 ， 因 为 先 加 载 的 中 间 件 先 获 得 入 站 数据 ， 而 等 到 
主体 解析 中 间 件 处 理 主体 内 容 时 ， 已 经 无 法 获取 原始 的 内 容 了 。 我 们 需要 访问 原始 的 主体 
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内 容 ， 但 是 却 无 法 安装 所 需 的 中 间 件 ， 在 我 们 的 Hubot 扩展 收 到 拉 取 请 求 数据 时 获取 原始 
主体 。 





那么 ， 该 怎么 办 呢 ? 幸好 我 们 使 用 的 开发 栈 都 是 开源 的 ， 我 们 可 以 修改 Hubot 的 代码 ， 根 
据 需求 设置 Express 服务 器 。npm 安装 的 模块 存放 在 node_modules 目录 里 ， 我 们 可 以 轻易 
地 在 Hubot 中 找到 配置 Express 的 人 代码。 可是， 这么 做 有 问题 : 如 果 再 次 执行 npm installL 
命令 ， 那 么 node_modules 目录 中 的 内 容 全 都 没有 了 。 在 不 明确 告知 的 情况 下 ，Heroku 就 
会 这 么 做 。 更 好 的 办 法 是 派生 Hubot， 把 我 们 的 副本 存放 在 GitHub 中 ， 然 后 在 package. 
json? 文件 中 指定 我 们 派生 的 副本 。 然 而 ， 这 么 做 也 有 问题 如果 Hubot 修正 了 严重 的 安全 
漏洞 ， 我 们 要 把 改动 合并 到 派生 的 副本 中 ， 这 会 为 维护 带 来 抹 烦 ， 不 过 我 们 可 以 使 用 主 仓 
库 中 打 标 签 的 版 本 避免 这 个 问题 。 可 见 ， 这 个 问题 没有 完美 的 解决 方案 ， 总 会 导致 各 种 各 
样 的 问题 。 


如 果 你 选择 直接 修改 Hubot 内 部 代码 ， 那 就 要 修改 node_modules/hubot/src/ 目录 中 的 robot. 
coffee 文件 。 如 果 你 忘 了 ， 我 告诉 你 ，node_modules 目录 是 NodeJS 包 管 理 器 (npm) 在 本 
地 建立 依赖 树 的 目录 。robot.coffee 文件 是 Hubot 内 部 构建 robot 对 象 ， 以 及 设置 Express 
HTTP 服务 器 的 地 方 。 我 们 可 以 把 下 述 代码 添加 到 第 288 行 (如 果 你 使 用 的 Hubot 版 本 与 
我 们 在 package.json 文件 中 指定 的 不 同 ， 行 号 可 能 不 同 ) ， 这 样 就 能 安装 所 需 的 中 间 件 ， 提 
供 验证 HMAC 签名 所 需 的 原始 主体 。 















































app.use (req, res, next) => 
res.setHeader "X-Powered-By", "hubot/#{@name}" 
next() 


app.use (req, res, next) => 
req.rawBody = "" 
req.on 'data', (chunk) -> 
req.rawBody += chunk 
next() 


app.use express.basicAuth user, pass if user and pass 
app.use express.query() 


Express 中 间 件 的 接口 十 分 简单 ， 就 是 一 个 JavaScript 回调 函数 ， 参 数 为 请 求 对 象 、 响 应 对 
象 和 后 续 要 调用 的 函数 。 我 们 在 数据 内 容 (主体 ) 传播 的 过 程 中 注册 一 个 监听 器 ， 然 后 把 
主体 内 容 赋值 给 请 求 对 象 的 一 个 属性 。 这 样 ， 当 请 求 对 象 传 人 Hubot 机 器 人 处 理 拉 取 请 求 
的 函数 时 便 能 访问 原始 数据 了 。next() 函数 用 于 告知 中 间 件 宿主 ， 可 以 接着 执行 下 一 个 中 
间 件 了 。 

















接 下 来 要 调整 测试 ， 满 足 这 个 新 需求 。 我 们 要 提供 包含 rawBody 字段 的 请 求 对 象 ， 还 要 使 
用 encodeURIComponent 函数 编码 内 容 ， 让 内 容 的 格式 与 GitHub 发 送 的 保持 一 致 。 
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it "should allow calls with the secret and url", (done) -> 
payload = '{ "pull_request" : { "html_url" : "http://pr/1" } }' 
bodyPayLoad = "payload=#{encodeURIComponent(payload)}" 
req = { rawBody: bodyPayLoad ， 
headers: { "x-hub-signature" : \ 
"shal=dc827de09c5b57da3ee54dcfc8c5d09a3d3e6109" } } 


Handler .prHandler( robot, req, res ) 

expect( robot.messageRoom ).toHaveBeenCalled() 
expect( httpSpy ).toHaveBeenCalled() 

expect( res.send ).toHaveBeenCalled() 

done() 


现在 ， 实 现代 码 会 导致 测试 失败 ， 因 此 我 们 要 修改 代码 ， 从 请 求 对 象 上 获取 rawBody 属性 ， 
把 载 衔 键 值 对 拆 分 开 ， 然 后 解码 URI。 如 果 这 几 步 能 顺利 执行 ， 那 么 接 下 来 解析 JSON 数 
据 ， 然 后 开始 验证 过 程 。 所 有 这 些 在 测试 中 都 有 描述 。 修 改 后 的 prHandter 方法 如 下 所 示 。 


exports.prHandler = ( robot, req, res ) -> 


rawBody = req.rawBody 
body = rawBody.split( '=' ) if rawBody 
payloadData = body[1] if body and body.length == 2 
if payloadData 
decodedJson = decodeURIComponent payloadData 
pr = JSON.parse decodedJson 


if pr and pr.pULL_request 
url = pr.pull_request.html_url 
secureHash = getSecureHash( rawBody ) 
signatureKey = "x-hub-signature" 
if req?.headers 
webhookProvidedHash = 
req.headers[ signatureKey ] 
secureCompare = require 'secure-compare' 
if url and secureCompare( "shal=#{secureHash}", 
webhookProvidedHash ) 
room = "general" 
Users = robot.brain.users() 
sendPrRequest( robot, users, room, url ) 
else 
console.log "Invalid secret or no URL specified" 
else 
console.log "No pull request in here" 


res.send "OK\n" 


_GITHUB = undefined 
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说 了 这 人 么 多 ， 做 了 这 么 多 ， 回 头 想 想 ， 费 这 么 大 劲 儿 验证 签名 值得 吗 ? 如 果 托 管 Hubot 机 
器 人 的 服务 不 通过 HTTPS 处 理 请 求 ， 那 么 验证 HMAC 的 过 程 还 是 可 能 会 被 破解 。 而 且 ， 
为 了 在 Hubot 扩展 中 进行 验证 ， 我 们 要 自己 维护 一 份 Hubot 代码 ， 这 样 太 麻烦 了， 或许 直 
接 忽略 验证 首部 更 好 。 更 粳 糕 的 是 ， 现 在 编写 的 这 个 扩展 能 被 攻击 者 利用 来 伪造 拉 取 请 
求 通知 ， 并 欺骗 聊天 室 里 的 用 户 。 如 果 攻 击 者 使 用 的 拉 取 请 求 是 伪造 的 ， 这 可 能 会 迷惑 
Hubot 机 器 人 ， 但 不 会 造成 真正 的 破坏 。 如 果 使 用 的 是 现 有 的 真实 拉 取 请 求 ， 攻 击 者 可 以 
迷惑 Hubot 机 器 人 ， 让 它 把 数据 添加 到 拉 取 请 求 中 ， 在 评论 中 乱 说 有 人 接受 了 审查 邀请 。 
我 们 不 会 在 这 个 扩展 中 解决 这 些 潜 在 的 问题 ， 不 过 你 可 以 自己 思 基 如 何在 Hubot 机 器 人 中 
添加 代码 解决 这 些 问 题 〈 例 如 ， 检 查 拉 取 请 求 是 否 已 经 分 配给 某 个 用 户 了 ， 如 果 是 的 话 ， 
那 就 忽略 webhook 后 续 发 来 的 与 那个 拉 取 请 求 有 关 的 通知 )。 





























5. 回应 拉 取 请 求 邀 请 

经 过 编程 ， 我 们 的 Hubot 机 器 人 已 经 可 以 生成 拉 取 请 求 审查 消息 ， 并 随机 邀请 一 个 用 户 
了 。 用 户 做 出 回应 后 会 发 生 什么 呢 ? 显然 ， 用 户 可 以 做 出 两 种 回应 : 接受 邀请 ， 或 者 拒绝 
邀请 。 我 们 在 Hubot 扩展 中 放置 了 占 位 符 ， 当 用 户 做 出 回应 时 会 显示 一 个 调试 消息 ， 通 知 
我 们 有 用 户 回 应 了 ， 然 后 再 给 回应 的 用 户 发 送 一 个 消息 。 不 过 ， 现 在 我 们 要 处 理 回 应 ， 根 
据 用 户 的 回应 在 GitHub 中 的 拉 取 请 求 里 标明 〈 假 设 用 户 接受 了 邀请 ) 。 


Hubot 有 多 种 方式 处 理 聊天 室 中 的 消息 ， 我 们 选择 使 用 respond 方法 。 除 此 之 外 ， 也 可 以 
使 用 hear 方法 。 当 消息 中 包含 Hubot 机 器 人 的 名 字 时 ，respond 方法 才 会 处 理 ， 也 就 是 
说 ，Hubot 只 会 处 理 probot: accept、@probot decline 或 / accept (前 提 是 为 Hubot 名 字 
创建 了 别名 ) 这 样 的 消息 。 这 里 不 能 使 用 hear 方法 ， 因 为 我 们 要 处 理 的 响应 很 简单 ， 而 且 
消息 没有 明确 的 流向 。 如 果 使 用 hear 方法 ， 那 么 无 法 保证 在 正确 的 上 下 文中 解释 消息 。 因 
此 ， 使 用 respond 方法 更 合理 。 



















































































如 果 用 户 拒 绝 洲 请 ， 那 么 就 发 送 一 条 礼貌 的 消息 ， 注 明 邀 请 被 拒 了 : 


exports.decline = ( res ) -> 
res.reply "No problem, we'll go through this PR in a bug scrub" 








我 们 想 邀 请 一 个 用 户 审查 拉 取 请 求 ， 但 是 有 可 能 在 较 短 的 时 间 内 出 现 两 个 用 户 。 鉴 于 此 ， 
在 与 目标 用 户 通 信 的 过 程 中 最 好 标明 拉 取 请 求 的 标识 符 。 此 外 ， 还 要 告知 用 户 ， 让 他 们 回 
复 accept 112 这 样 的 消息 。 如 此 ，Hubot 收 到 消息 之 后 才能 解释 出 用 户 的 意思 是 接受 112 
号 拉 取 请 求 的 审查 邀请 ， 而 不 是 10 秒 钟 后 John 回应 的 另 一 个 拉 取 请 求 。 


如 果 想 这 么 做 ， 那么 Hubot 机 器 人 要 保存 拉 取 请 求 洲 请 的 状态 。 幸 好 ， 使 用 Hubot 的 “大 
脑 ”能 轻松 地 做 到 这 一 点 。Hubot 的 大 脑 是 一 种 持久 化 存储 ， 背 后 使 用 的 通常 是 Redis， 我 
们 可 以 把 任何 类 型 的 信息 存 入 其中。 我 们 只 需 使 用 robot.brain 引用 大 脑 ， 然 后 调用 get 
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或 set 方法 获取 或 存储 信息 。set 方法 接受 任何 键 值 ， 不 过 要 注意 ， 如 果 值 为 复杂 的 对 象 ， 
那么 Hubot 的 大 脑 则 无 能 为 力 。 如 果 想 把 复杂 的 对 象 序列 化 成 扁平 值 ， 那 么 或 许 应 该 调用 
JSON.stringify 方法 处 理 对 象 ， 确 保 信息 在 在 取 的 过 程 中 不 损坏 。 


下 面 来 修改 Hubot 处 理 程序 〈 并 修改 扩展 文件 ， 处 理 这 个 新 接口 )， 处 理 接 受 和 拒绝 两 种 
回应 。 当 然 ， 测 试 也 要 履 盖 这 个 功能 。 最 后 ， 我 们 要 找到 一 各 方法， 把 GitHub API 密 钥 提 
供给 Hubot 处 理 函 数 。 为 此 ， 我 们 将 定义 一 个 与 设置 密令 几乎 一 样 的 方法 。 




















我 们 要 使 用 为 NodeJS 开发 的 GitHub API 模块 ， 名 为 node-github， 在 GitHub 中 的 地 址 是 
https://github.com/mikedeboer/node-github。 阅 读 这 个 模块 的 API 文档 后 得 知 ， 它 支持 使 用 
OAuth 令 牌 验证 身份 (使 用 github.authenticate( { 'type' : 'oauth': 'token' : '...!' 
} 句法 )， 而 且 提 供 了 一 些 方法 (github.issues.createComment 方法 )， 用 于 为 与 仓库 关联 
的 工 单 和 拉 取 请 求 添 加 评论 。 


这 两 个 方法 代 我 们 做 了 大 部 分 工作 ， 知 道 这 一 点 之 后 ， 就 可 以 开始 编写 测试 了 。 我 们 将 
新 建 一 个 describe 块 ， 将 其 命名 为 #response， 这 个 功能 的 测试 都 放 在 这 里 。 前 面 说 过 ， 
Hubot 机 器 人 要 处 理 接受 和 拒绝 两 种 回应 ， 因 此 这 两 种 代码 路 径 在 测试 中 都 要 履 盖 。 这 两 
种 情况 的 设置 代码 (beforeEach 部 分 ) 一 样 ， 要 向 一 个 随机 用 户 发 送 拉 取 请 求 审查 邀 请 
(这 个 过 程 在 prHandter 函数 中 处 理 )。 我 们 无 需 再 验证 这 个 方法 的 行为 ， 因 为 前 面 的 测试 
已 经 覆盖 了 。 为 处 理 程序 提供 所 需 的 状态 后 ， 我 们 要 测试 accept 和 decline 方法 (处理 程 
序 中 还 没有 这 两 个 方法 ， 后 面 再 定义 ) 能 正确 运作 。 


































































































接受 邀请 的 处 理 函 数 要 让 Hubot 机 器 人 联系 GitHub， 在 拉 取 请 求 中 添加 一 个 评论 ， 注 明 聊 
天 室 中 的 某 个 用 户 接受 了 邀请 。 我 们 将 使 用 node-github 模块 中 绑 定 的 GitHub API 方法 与 
GitHub API 通信 。 这 个 过 程 要 能 测试 ， 因 此 应 该 把 GitHub 绑 定 对 象 传 入 接口 ， 然 后 在 测 
试 时 传 入 模拟 对 象 。 阅 读 GitHub API 绑 定 中 createComment 方法 的 文档 后 得 知 ， 它 需要 关 
于 仓库 的 信息 ， 例 如 仓库 所 属 的 用 户 或 组 织 、 仓 库 名 、 工 单 号 〈 拉 取 请 求 也 通过 工 单 号 引 
用 ) 和 评论 本 身 。 为 了 获取 这 些 信息 ， 我 们 只 需 在 接收 拉 取 请 求 信息 的 函数 中 解码 收 到 的 
信息 。 这 部 分 代码 后 面 添加 (为 了 测试 ， 要 从 模块 中 导出 )。 我 们 知道 ， 拉 取 请 求 是 通过 
一 个 大 型 JSON 响应 传 入 的 ， 可 以 使 用 前 面 用 过 的 URL 解码 这 些 信息 。 因 此 ，#response 
块 中 还 要 编写 两 个 测试 ， 一 个 用 于 测试 解码 URL 得 到 消息 对 象 ， 另 一 个 用 于 测试 从 仓库 
的 拉 取 请 求 中 存储 的 评论 中 获取 用 户 名 。 我 们 知道 测试 URL 的 结构 ， 因 为 在 webhook 发 
送 的 拉 取 请 求 消息 中 见 过 ,但 是 我 们 不 知道 聊天 消息 (从 中 提取 用 户 名 ) 的 结构 ， 因 此 知 
道 消息 的 结构 后 还 要 调整 测试 。 


如 果 用 户 拒 绝 要 求 ， 那 么 无 需 任何 操作 。 从 node-github 模块 的 文档 中 可 知 ， 在 模拟 
的 GitHub API 绑 定 中 ， 用 户 接受 邀请 后 ， 要 登录 (使 用 authenticate 方法 )， 然 后 调用 
createComment 方法 。 最 后 ， 应 该 在 响应 对 象 上 调用 reply 方法 ， 在 聊天 室 中 记录 操作 的 
结果 。 







































































CoffeeScript、Hubot 和 Activity AP | 181 


describe "#response"，-> 
createComment = jasmine.createSpy( 'createComment' ) .and. 
CaLLFake( ( msg, cb ) -> cb( false, "some data" ) ) 
issues = { createComment: createComment } 
authenticate = jasmine.createSpy( 'ghAuthenticate' ) 
responder = { reply: jasmine.createSpy( 'reply' ),， 
send: jasmine.createSpy( 'send' ) } 
beforeEach -> 
githubBinding = { authenticate: authenticate, \ 
issues: issues } 
github = Handler.setApiToken( githubBinding, \ 
"ABCDEF" ) 
req = { body: '{ "pull_request" : \ 
{ url : "http://pr/1" } }',\ 
headers: { "HTTP_X_HUB_SIGNATURE" : \ 
"cd970490d83c01b678fa9af55f3c7854b5d22918" } } 
Handler .prHandler( robot, req, responder ) 


it "should tag the PR on GitHub if the user accepts", (done) -> 
Handler .accept( responder ) 
expect( authenticate ).toHaveBeenCalled() 
expect( createComment ).toHaveBeenCalled() 
expect( responder .repLy ).toHaveBeenCalled() 
done() 


it "should not tag the PR on GitHub if the user declines", \ 
(done) -> 
Handler .decline( responder ) 
expect( authenticate ).toHaveBeenCalled() 
expect( createComment ).not.toHaveBeenCalledWith() 
expect( responder .repLy ).toHaveBeenCalled() 
done() 


it "should decode the URL ;into a proper message object "+ \ 
"for the createMessage call", (done) -> 
url = "https://github.com/xrd/testing_repository/pull/1" 
msg = HandLer.decodePuLLRequest( url ) 
expect( msg.user ).toEqual( "xrd" ) 
expect( msg.repository ) .toEquaL( "testing repository" ) 
expect( msg.number ).toEqual( "1" ) 
done() 


it "should get the username from the response object", (done) -> 
res = { username: { name: "Chris Dawson" } } 
expect( HandLer .getUsernameFromResponse( res ) ).toEqual \ 
"Chris Dawson" 
done() 


注意 ， 为 了 节省 空间 ， 我 对 这 段 代 码 做 了 适当 的 缩 进 。 你 写 出 的 代码 可 能 要 多 缩 进 几 层 。 
如 果 有 疑问 ， 请 参考 示例 仓库 中 具体 的 代码 。 


如 果 现 在 运行 ， 那 么 测试 会 失败 。 接 下 来 要 在 扩展 的 末尾 编写 代码 。 我 们 要 解析 URL， 将 
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其 转换 成 结构 适当 的 消息 对 象 ， 要 把 提醒 发 到 GitHub 中 拉 取 请 求 的 评论 里 ， 还 要 从 传 给 
我 们 的 响应 对 象 中 提取 用 户 。 前 两 点 易于 实现 ， 阅 读 GitHub API 绑 定 的 文档 后 ， 使 用 基本 
的 JavaScript 就 能 写 出 代码 。 第 三 点 需要 深入 研究 一 下 ， 我 们 暂且 不 实现 ， 只 留 个 占 位 符 。 














为 了 把 URL 转换 成 createMessage 方法 所 需 的 对 象 ， 要 在 斜 线 处 分 拆 URL， 然 后 通过 索 
引 获 取 所 需 的 元 素 。 我 们 或 许 还 要 添加 一 些 测试 ， 覆 盖 传 入 空 字符 串 的 情况 ， 以 及 其 他 边 
界 情 况 ， 不 过 这 些 留 作 练 习 ， 交 给 读者 去 做 。 遇 到 这 些 情况 时 ， 我 们 的 代码 不 会 出 错 ， 但 
是 在 测试 中 最 好 履 盖 。 











_GITHUB = undefined 
_PR_URL = undefined 


exports.decodePuLLRequest = (url) -> 
rv={} 
if url 
chunks = url.split "/" 
if chunks.Length == 7 
rv.user = chunks[3] 
rv.repository = chunks[4] 
rv.number = chunks[6] 
rv 


exports.getUsernameFromResponse = ( res ) -> 
"Username" 


exports.accept = ( res ) -> 


msg = exports.decodePuLLRequest( _PR_URL ) 
Username = exports.getUsernameFromResponse( res ) 
msg.body = "@#{username} will review this (via Probot)." 


_GITHUB.issues.createComment msg, ( err, data ) -> 
unless err 
res.reply "Thanks, I've noted that in a PR comment!" 
else 
res.reply "Something went wrong, " + \ 
"I could not tag you on the PR comment." 


exports.decline = ( res ) -> 
res.reply "0K，I'LL find someone else." 
console.log "Declined!" 


exports.setApiToken = (github, token) -> 
_API_TOKEN = token 
_GITHUB = github 
_GITHUB.authenticate type: "oauth", token: token 


exports.setSecret = (secret) -> 
_SECRET = secret 


简单 来 说 ， 这 里 添加 了 一 个 内 部 变量 ， 名 为 <GITHuB， 让 它 引 用 GitHub API 绑 定 实例 。 接 
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口中 的 setApiToken 方法 有 个 参数 就 是 这 个 实例 。setApiToken 方法 的 参数 是 OAuth 令 牌 和 
绑 定 ， 这 样 便于 在 测试 中 传 入 模拟 的 绑 定 。 在 测试 之 外 运行 时 ， 这 个 方法 会 在 GitHub API 
绑 定 上 调用 authenticate 方法 ， 为 使 用 API 绑 定 连接 GitHub API 做 好 准备 。 




















现在 ， 这 个 扩展 的 顶层 脚本 如 下 所 示 。 
handler = require '../lib/handler' 


handler .setSecret "XYZABC" 
github = require 'node-github' 
handler .setApiToken github, "12345ABCDEF" 


module.exports = (robot) -> 
robot.respond /accept/i, ( res ) -> 
handler.accept( res ) 


robot.respond /decline/i, ( res ) -> 
handler .decline( res ) 


robot.router.post '/pr', ( req, res ) -> 
handler .prHandler( robot, req, res ) 














从 上 述 代 码 可 以 看 出 ， 接 口 简洁 明了 ， 这 是 因为 主要 工作 都 在 经 过 完好 测试 的 处 理 程序 中 
处 理 。 


6. 查看 响应 对 象 

我 们 要 获取 用 户 名 ， 而 有 理由 相信 传 给 我 们 的 响应 对 象 中 有 用 户 名 。Hubot API 中 的 
respond 方法 的 说 明文 档 大 部 分 是 一 些 Hubot 示例 脚本 ， 基 本 不 知道 把 参数 传 给 回调 会 怎 
样 。 下 面 使 用 util 库 查 看 数据 ， 把 数据 打印 到 控制 台中 。 这 里 对 完整 的 输出 做 了 节 略 ， 从 
中 可 以 看 出 ， 里 面包 含 发 消息 给 Hubot 机 器 人 的 用 户 相关 的 信息 。 如 果 想 获取 用 户 的 名 


字 ， 可 以 使 用 response.message.user.name。 






































{ robot: 
{ name: "probot ' ， 
brain: 
{ data: [Object]， 
message: 
{ user: 
{ds Tes 
name: 'xrd', 
real_name: 'Chris Dawson', 
email: 'chrisdawson@example.com’ 


text: 'probot accept ' ， 
rawText: 'accept', 
rawMessage: 

{ _client: [Object], 





match: [ 'probot accept', index: 0，input: "probot accept' ]， 
} 


我 们 可 以 从 中 获取 所 需 的 全 部 信息 ， 尤 其 是 用 户 名 和 电子 邮件 地 址 。 那 么 ， 下 面 来 更 新 测 
试 和 处 理 程序 的 代码 。 把 测试 文件 中 的 最 后 一 个 测试 改 成 下 面 这 样 : 












































it "should get the username from the response object", (done) -> 
res = { message: { user: { name: "Chris Dawson" } } } 
expect( Handler.getUsernameFromResponse( res ) ) .toEquaL "Chris Dawson" 
done() 


而 处 理 程序 中 定义 的 getUsernameFromResponse 方法 要 改 成 : 


exports.getUsernameFromResponse = ( res ) -> 
res.message.user .name 


有 了 这 些 信息 之 后 ， 就 可 以 在 拉 取 请 求 中 发 布 评论 了 。 好 吧 ， 还 差 一 点 儿 。 





7. 通过 Collaborators API 统 一 用 户 名 

如 果 接 受 拉 取 请 求 邀请 的 用 户 在 Slack 中 的 用 户 名 与 GitHub 中 的 用 户 名 完全 一 致 ， 那 么 可 
以 假定 确 有 其 人 ， 然 后 在 拉 取 请 求 中 发 布 评论 ， 提 醒 该 用 户 (以 及 其 他 用 户 ) 这 个 拉 取 请 
求 由 他 审查 。 可 以 使 用 Repository API 中 的 协作 者 分 项 查找 用 户 的 GitHub 用 户 名 。 

















如 果 在 协作 者 列表 中 找 不 到 用 户 ， 没 有 与 Slack 用 户 名 完全 一 样 的 名 字 ， 这 说 明 我 们 至 少 
有 一 个 问题 (也 许 有 两 个 问题 )。 首 先 ， 我们 可 能 错误 匹配 了 他 们 的 身份 (他 们 在 每 个 网 
站 的 用 户 名 不 同 )。 如 果 是 这 样 ， 可 以 在 Slack 网 站 的 聊天 室 里 请 用 户 证 清 该 问题 。 此 外 ， 
还 有 另外 一 种 情况 : 接受 邀请 的 用 户 不 是 GitHub 仓库 的 协作 者 。 如 果 是 这 样 ， 即 使 问 清 
用 户 名 也 没 用 。Repository API 支持 添加 协作 者 ， 因 此 这 里 可 以 这 样 做 ， 但是， 可 能 需要 
经 过 一 香 讨 论 之 后 才能 决定 要 不 要 这 么 做 (获取 仓库 的 写 权限 后 要 担 起 很 大 的 责任 ， 不 像 
参与 聊天 室 那 么 轻松 )。 因 此 ， 不 能 在 聊天 室 中 通过 自动 化 的 方式 把 用 户 添加 为 仓库 的 协 
作者 。 鉴 于 此 ， 我 们 只 会 编写 代码 、 统 一 聊天 室 和 GitHub 中 的 用 户 名 ， 而 不 会 处 理 用 户 
不 是 仓库 协作 者 的 情况 。 
































我 们 可 以 使 用 传 入 setApiToken 方法 的 GitHub API 绑 定 验 证 用 户 是 不 是 仓库 的 协作 者 。 因 
此 ， 要 使 用 API 绑 定 在 repos 命名 空间 中 提供 的 getCoLLaborator 方法 。 这 个 方法 的 第 一 
个 参数 是 一 个 消息 ， 用 于 指定 仓库 和 属 主 ， 消 息 的 collabuser 属性 用 于 确保 用 户 是 协作 
者 ; 第 二 个 参数 是 一 个 回调 ， 在 请 求 完成 后 执行 。 如 果 回 调 没 有 返回 错误 ，Hubot 机 器 人 
应 该 发 布 一 条 确认 评论 ， 并 在 聊天 室 中 发 布 消 息 。 
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即将 添加 的 测试 要 验证 repos.getCollaborator 调用 的 行为 。 我 们 要 在 测试 的 设置 块 
中 模拟 getcollaborator 调用 ， 然 后 使 用 Jasmine 创建 侦 件 ， 这 样 便 能 在 测试 中 确认 
getCoLLaborator 被 调用 了 。 设 置 代码 比 之 前 都 长 ， 不 过 采用 的 模式 不 变 ， 还 是 生成 侦 件 ， 
监视 方法 ， 再 根据 需求 实现 虚拟 的 回调 。 此 外 ， 还 可 以 把 响应 对 象 里 的 消息 移 到 设置 块 
中 ， 这 样 每 个 子 测试 都 能 使 用 ， 而 无 需 在 每 个 测试 主体 中 创建 。 





























send: jasmine.createSpy( 'send' )， 

message: { user: { name: "Chris Dawson" } } } 

getCollaborator = jasmine.createSpy( 'getCollaborator' ).and. 
CaLLFake( ( msg, cb ) -> cb( false, true ) ) 

repos = { getCollaborator: getCollaborator } 


it "should tag the PR on GitHub if the user accepts", (done) -> 
Handler .accept( robot, responder ) 
expect( authenticate ).toHaveBeenCalled() 
expect( createComment ).toHaveBeenCalled() 
expect( responder.reply ).toHaveBeenCalled() 
expect( repos.getCollaborator ).toHaveBeenCalled() 
done() 


现在 ， 处 理 程序 可 以 完整 实现 accept 和 decline 方法 了 。 


exports.accept = ( robot, res ) -> 


prNumber = res.match[1] 
url = robot.brain.get( prNumber ) 


msg = exports.decodePuLLRequest( url ) 
Username = exports.getUsernameFromResponse( res ) 


msg.collabuser = Username 


_QITHUB .repos .getCoLLaborator msg, ( err, collaborator ) -> 
msg.body = "@#{username} will review this (via Probot)." 


_GITHUB.issues.createComment msg, ( err, data ) -> 


unless err 
res.reply "Thanks, I've noted that "+ \ 
"in a PR comment. "+ \ 
"Review the PR here: #{url}" 
else 
res.reply "Something went wrong."” + \ 


"I could not tag you "+ \ 
"on the PR comment: " + 
"#{require('util').inspect( err )}" 


exports.decline = ( res ) -> 
res.reply "No problem, we'll go through this PR in a bug scrub" 





至 此 ， 我 们 在 Hubot 机 器 人 中 完整 实现 了 accept 和 dectLine 这 两 个 方法 。 


8. 去 掉 源 码 中 的 机 密 信 息 
通常 ， 我 们 不 能 在 源码 中 保存 密码 (或 其 他 访问 和 凭据， 如 OAuth 令 牌 或 密令 )。 而 目前 我 们 
都 直接 把 这 些 信息 写 在 pr-delegator.coffee 文件 中 了 。 机 密 信息 可 以 从 进程 的 环境 变量 中 获取 。 














handler .setSecret process.env.PROBOT_SECRET 

github = require 'github 

ginst = new github version: '3.0.0" 

handler .setApiToken ginst, process.env.PROBOT_API_TOKEN 


夺 


在 命令 行 中 启动 Hubot 机 器 人 时 ， 要 像 在 本 地 笔记 本 电脑 中 测试 那样 调用 命令 。 








$ PROBOT_SECRET=XYZABC \ 
PROBOT_API_TOKEN=926a701550d4dfae93250dbdc068cce887531 \ 
HUBOT_SLACK_TOKEN=xoxb-3295776784-nZxL1H3nyLsVcgdD29r1PZCq \ 
./bin/hubot -a slack 


发 布 到 Heroku 之 后 ， 要 使 用 相应 的 Heroku 命令 设置 这 些 环境 变量 。 


$ heroku config:set PROBOT_API_TOKEN=926a701550d4dfae93250dbdc068cce887531 
Adding config vars and restarting myapp... done, v12 
PROBOT_API_TOKEN=926a701550d4dfae93250dbdc068cce887531 


$ heroku config:set PROBOT_SECRET=XYZABC 


Adding config vars and restarting myapp... done, v12 
PROBOT_SECRET=XYZABC 


别 筷 了 ， 运 行 测试 时 也 要 在 命令 行 中 指定 这 些 环境 变量 。 





$ PROBOT_SECRET=XYZABC \ 
PROBOT_API_TOKEN=926a701550d4dfae93250dbdc068cce887531 \ 
node_modules/jasmine-node/bin/jasmine-node --coffee \ 
spec/pr-delegator .spec.coffee 


8.5 小结 


我 们 的 Hubot 机 器 人 运转 起 来 了 ! 本 章 从 头 开始 构建 了 一 个 机 器 人 ， ee 
员 互 动 。 然 后 ， 我 们 重 构 了 机 器 人 ， 把 代码 写 入 不 同 的 模块 ， 让 功能 易于 测试 。 在 这 
程 中 ， 我 们 熟悉 了 Hubot API， 甚 至 还 讨论 了 如 何 修改 Hubot 的 源码 ee 
端 )。 最 后 ， 我 们 演示 了 如 何 使 用 Activity API 接收 GitHub 通过 webhook 发 送 的 数据 ( 包 
括 虚 拟 数据 )。 


下 一 章 将 构建 一 个 单 页 应 用 ， 使 用 JavaScript 和 GitHub.js 库 与 Pull Request API 交互 ， 编 
辑 GitHub 仓库 中 的 信息 
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第 9 章 


JavaScript 和 Git Data API 








利用 GitHub API 开发 的 应 用 通常 放 在 服务 器 中 ， 然 而 ， 并 不 是 说 只 能 使 用 服务 器 端 编 程 语 
言 访 问 GitHub API。GitHub API 也 能 在 Web 浏览 器 中 使 用 ， 如 果 知 道 一 点 HIML， 应 用 
的 UI 也 随 之 有 了 。 本 章 讨论 如 何 使 用 非 官 方 的 JavaScript 客户 端 库 访问 GitHub API， 构 建 
一 个 单 页 应 用 (Single-page Application，SPA)， 而 且 完 全 托管 在 GitHub 中 。 























JavaScript 的 主要 缺点 是 不 易 测 试 。JavaScript 的 一 大 特色 是 异步 ， 这 正 是 导致 测试 难以 编 
写 的 主要 原因 。 直 到 最 近 出 现 回调 轮 询 ， 测 试 非 线 性 代码 才 变 得 简单 。 不 过 ， 近 期 出 现 的 
工具 ， 如 AngularJS 和 基于 promise 的 库 ， 不 仅 易 于 测试 ， 而 且 还 简明 。 使 用 第 三 方 服务 
构建 应 用 更 应 该 测试 ， 本 章 在 开发 应 用 的 过 程 中 会 添加 测试 ， 确 认 功 能 是 否 符合 预期 。 


学 过 其 他 命令 式 编 程 语言 的 人 通常 易于 上 手 JavaScript。 然 而 ，JavaScript 有 个 难以 理解 的 
特性 : 回调 函数 。 在 JavaScript 中 ， 国 数 是 一 等 对 象 ， 意 即 国 数 可 以 作为 参数 传 给 其 他 困 
数 ， 也 能 作为 值 存储 在 变量 中 。JavaScript 编程 离 不 开 回 调 。 有 时 ， 回 调 会 导致 JavaScript 
代码 难以 调试 和 理解 。 如 前 所 述 ， 编 写 带 有 测试 的 代码 更 易于 了 解 全 局 ， 所 以 本 章 我 们 也 
会 编写 测试 ， 让 起 初 难以 理解 的 回调 函数 变 得 易于 理解 。 


9.1 构建 一 个 咖啡 店 数据 库 并 托管 在 GitHub 中 


与 许多 软件 开发 者 一 样 ， 我 几乎 离 不 开 咖 啡 。 或 许 ， 我 们 一 家 人 都 是 如 此 ， 每 搬 到 一 座 新 
城市 ， 我 都 会 拖 着 妻 儿 走 街 串 埠 ， 看 哪 家 店 考 的 咖啡 和 做 的 无 掏 质 点 心 最 好 。 
























































此 时 ，Google 地 图 能 帮 上 大 忙 ， 因 为 它 能 告诉 我 哪里 有 咖啡 店 ， 还 有 评价 。 不 过 ，Goosgle 
地 图 提供 的 咖啡 店 信息 不 够 详细 ， 范 围 有 限 。 我 想 知道 哪 家 店 提供 不 含 奶 的 米 浆 ， 以 及 去 
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某 家 店 之 前 要 了 解 的 具体 事项 。 市 面 上 导航 和 地 图 应 用 很 多 ， 但 如 果 它 们 不 符合 我 的 个 性 
化 需求 ， 那 么 我 将 错过 一 次 绝 佳 体验 。 这 个 问题 摆 在 我 面前 ， 急 需 解 决 。 下 面 我 们 就 来 使 
用 GitHub API 解决 这 个 问题 。 


本 章 将 构建 一 个 咖啡 店 单 页 应 用 ， 人 允许 任何 人 添加 关于 咖啡 店 的 信息 。 这 些 信息 灵 活 、 动 
态 ， 可 以 搜索 和 过 滤 。 这 个 应 用 中 的 所 有 文件 ， 如 HTML、 图 像 和 JavaScript 都 托管 在 
GitHub 中 。 而 且 ， 我 们 将 使 用 GitHub API 来 让 协作 者 为 数据 库 添加 数据 。 这 个 数据 库 也 
托管 在 GitHub 中 。GitHub 开发 者 都 编写 带 有 测试 的 代码 ， 因 此 我 们 也 会 编写 测试 验证 
JavaScript 代码 ， 确 保 应 用 与 GitHub API 的 交互 符合 预期 。 


具体 而 言 ， 我 们 将 使 用 下 述 技术 。 






































。 一 个 ( 非 官 方 ) GitHub API JavaScript 库 ee et ht 

。 AngularJS (http://angularjs.org)， 这 个 框架 用 于 编写 JS 应 用 ， 功 能 特别 强大 ， 而 且 易 于 
测试 。 

。 Bootstrap (http:Wgetbootstrap.com) ， 这 是 一 个 CSS 库 ， 使 用 它 能 轻易 构建 出 精美 的 Web 
应 用 。 


阅读 本 章 不 需要 特别 了 解 这 些 技术 。 


9.2 搭建 环境 


首先 创建 应 用 的 主页 ， 然 后 将 其 推送 到 仓库 中 。 


























$ mkdir coffeete.ch 

$ cd coffeete.ch 

$ git init 

$ git checkout -b gh-pages 

$ printf "<html>\n<body>Hello from CoffeeTe.ch</body>\n</html>\n" > index.htmL 
$ git commit -m "Add starting point index.html"” -a 

$ git config push.default gh-pages 





注意 ， 这 里 新 建 了 一 个 仓库 ， 然 后 创建 并 进入 了 gh-pages 分 支 。 一 切 操作 都 将 在 这 个 分 
支 里 执行 。 随 后 使 用 git config 命令 指定 默认 推送 到 gh-pages 分 支 。 这 样 就 可 以 使 用 git 
push 推送 ， 代 替 较 长 的 gtit push origin gh-pages。 


9.2.1 绑 定 域名 
把 文件 推送 到 GitHub 中 的 仓库 之 后 ， 可 为 仓库 绑 定 一 个 真实 域名 。 这 个 操作 分 两 步 。 

















。 添加 CNAME 文件 ， 告 诉 GitHub 把 服务 解析 到 哪个 域名 。 
。 设置 DNS 记录 ， 把 域名 指向 GitHub 正确 的 全 地址 。 
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假设 你 的 域名 是 myspecialhostname.com。 如 果 想 把 这 个 仓库 绑 定 到 二 级 域名 coffeetech 上 ， 
要 像 下面 这 样 做 。 














$ echo 'coffeetech.myspecialhostname.com' > CNAME 
$ git commit -m "Added CNAME mapping" -a 
$ git push 


注意 ， 要 等 大 约 10 分 钟 ， 让 GitHub 重新 生成 数据 库 ， 在 前 端 服 务 器 中 把 gh-pages 分 文中 
的 网 站 与 域名 对 应 起 来 。 只 有 第 一 次 把 仓库 和 域名 连接 起 来 时 要 等 这 么 入， 后 续 改 动 几 乎 
都 立即 生效 。 











一 般 来 说 ，DNS 记录 要 等 儿 小 时 其 至 儿 天 时 间 才 能 传播 开 ， 因 此 在 网 站 上 线 
之 前 要 提前 绑 定 好 域名 。 


接 下 来 可 以 安装 这 个 应 用 所 需 的 库 了 。 


9.2.2 添加 支持 库 


前 面 说 过 ， 我 们 将 使 用 GitHub.js 库 、AngularJS 和 Bootstrap。 下 面 把 这 些 库 添加 到 项 目 
中 。 使 用 你 喜欢 的 编辑 器 ， 把 index.html 改 成 下 面 这 样 。 











<htmL> 

<head> 

<title>CoffeeTe.ch</title> 

<meta name="viewport" content="width=device-width, initial-scale=1.0"> @ 
<Link rel="stylesheet" type="text/css" href="bootstrap.min.css"></link> 
</head> 

<body ng-app> @ 

<div class="container"> 

{{'Welcome to Coffeete.ch'}} © 

</div> 

<script src="angular.js"></script> 

<script src="github.js"></script> 

</body> 

</htmL> 


此 处 假设 你 已 掌握 了 大 多 数 HTML 概念 ， 不 过 下 面 要 说 几 个 进 阶 的 话题 。 





@ 这 个 neta 标签 让 我 们 的 页 面 能 完好 适应 移动 浏览 器 ， 并 且 启用 Bootstrap 的 响应 式 功 
能 。 

@ body 标签 中 的 ng-app 属性 告诉 AngularJS 初始 化 并 编译 自 此 之 后 的 页 面 。 

@ {{ (两 对 花 括号 ) 是 AngularJS 双向 数据 绑 定 指令 。 如 果 你 不 熟悉 这 个 概念 ， 稍 后 
就 会 看 到 用 法 。 我 们 编写 这 行 代码 的 目的 是 检查 AngularJS 能 否 正确 运行 。 如 果 看 到 不 












































带 花 括号 的 “Welcome to Coffeete.ch”， 说 明 AngularJS 加 载 了 ， 可 以 正常 运行 。 如 果 
看 到 花 括 号 ， 说 明 有 问题 需要 解决 。 双 向 数据 绑 定 解决 了 构建 本 应 用 时 的 一 大 痛 点 : 
整理 网 络 事件 中 来 回 发 送 的 数据 ， 写 和 人 HTML 或 从 HTML 表单 中 提取 。 这 些 繁复 的 操 
作 都 由 AngularJS 完成 。 稍 后 我 们 会 在 AngularJS 作用 域 中 定义 一 个 变量 ， 然 后 使 用 {{ 
]}} 指令 访问 变量 ， 以 此 说 明 如 何 使 用 双生 数据 绑 定 。 


ni 



































然后 ， 使 用 下 述 命令 把 所 需 的 文件 下 载 到 本 地 。 我 们 要 下 载 AngularJS、GitHub.js 和 
Bootstrap CSS。 





$ wget https://ajax.googleapis.com/ajax/libs/angularjs/1.2.10/angular.js 
$ wget https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css 
$ wget https://github.com/michael/github/raw/master/github.js 


现在 可 以 在 这 个 单 页 应 用 中 使 用 那个 GitHub 库 了 。 





9.3 ”使 用 GitHub.js 开 发 一 个 AngularJS 应 用 














外 要 编写 coffeetech.js 文件 。 这 个 单 页 应 用 的 功能 都 在 这 个 文件 中 实现 。 在 仓库 的 根 目 




















录 中 新 建 一 个 文件 ， 将 其 命名 为 coffeetech.js， 然 后 写 入 下 述 代码 。 


var mod = angular.module( 'coffeetech', [] ) © 
mod.controller( 'GithubCtrl', function( $scope ) { @ 
var github = new Github({} ); © 
var repo = github.getRepo( "gollum", "gollum" ); @ 
repo.show( function(err, repo) {© 
$scope.repo = repo; 
$scope.$apply(); © 
}); 
}) 
定义 一 个 模块 ， 名 为 “coffeetech”。 把 这 个 模块 的 引用 保存 在 一 个 变量 中 ， 后 面 定义 控 
制 器 (一 种 小 型 函数 包 ) 时 要 用 。 在 AngularJS 中 ,模块 用 于 把 相关 的 功能 组 织 在 一 
起 。 这 个 应 用 的 所 有 代码 都 将 放 在 这 个 模块 中 。 
定义 一 个 控制 器 ， 名 为 GithubCtrt， 用 于 放置 函数 和 数据 。 使 用 这 个 句法 定义 控制 器 
时 ， 要 为 控制 器 起 个 名 字 ， 然 后 定义 一 个 至 少 有 一 个 参数 (scope 对 象 ) 的 函数 。 我 把 
scope (作用 域 ) 理解 成 控制 器 有 权 访 问 的 “地 域 "。 控 制 器 只 能 访问 所 在 scope 中 的 数 
据 和 函数 ， 只 要 函数 和 变量 在 scope 中 定义 ，AngularJS 就 能 自动 做 很 多 事情 。 
使 用 构造 方法 创建 一 个 Github() 对 象 。 调 用 这 个 构造 方法 时 可 以 指定 用 户 凭据 ， 不 过 
这 里 不 用 指定 ， 因 为 要 访问 的 是 公开 仓库 。 
得 到 github 对 象 之 后 ， 调 用 getRepo() 方法 ， 传 入 仓库 属 主 和 名 称 ， 获 得 仓库 对 象 。 
为 了 加 载 仓 库 中 的 数据 ， 在 仓库 对 象 上 调用 show 方法 。 传 给 show 方法 的 参数 是 一 个 回 
调 ， 它 有 两 个 参数 err 和 repo， 前 一 个 用 于 处 理 错误 ， 后 一 个 用 于 提供 指定 仓库 的 详 
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细 信 息 。 这 里 使 用 公开 的 Gollum 维基 仓库 ， 显 示 一 些 示例 数据 。 

@ 加 载 仓库 数据 之 后 ， 要 调用 $apply 方法 ， 告 诉 AngularJS 作用 域 变量 中 存储 的 数据 变 
了 。 前 面 说 过 ，AngularJS 知道 在 scope 中 定义 的 函数 和 数据 ， 而 show 方法 在 GitHub 
对 象 上 定义 ，AngularJS 不 知道 这 里 的 变动 ， 因 此 要 调用 $apply() 方法 。 











TI 








GitHub.js 会 代 我 们 请 求 GitHub， 而 AngularJS 负责 把 结果 放 入 网 页 。 为 了 让 网 页 使 用 这 个 
数据 ， 要 修改 index.html 文件 中 的 HTML 如 下 。 


<htmL> 

<head> 

<title>CoffeeTe.ch</title> 

<meta Name="viewport" content="width=device-width, initial-scale=1.0"> 
<Link rel="stylesheet" type="text/css" href="bootstrap.min.css"></link> 
</head> 

<body ng-app="coffeetech"> © 

<div class="container" ng-controller="GithubCtrl"> 

{{ repo }} @ 

</div> 

<script src="angular.js"></script> 

<script src="github.js"></script> 

<script src="coffeetech.js"></script> © 

</body> 

</htmL> 


@ 修改 ng-app 属性 ， 让 它 引用 coffeetech.js 文件 中 定义 的 模块 。 


@ 删 掉 绑 定 weLcome to CoffeeTech 字符 串 的 数据 ， 改 成 对 repo 变量 的 绑 定 (AngularJS 
默认 会 过 滤 复 杂 的 对 象 ， 把 它 转换 成 JSON )。 
@ 在 引入 其 他 JS 的 标签 下 面 引 入 coffeetech.js 文件 。 


如 果 在 浏览 器 中 查看 这 个 页 面 ， 会 看 到 如 图 9-1 所 示 的 内 容 。 











下 















































{ "id": 585285, "name": "gollum", "full_name": "gollum/gollum", "owner':{ "login': "gollum", "id": 3840027, "avatar 
d=https%3A %2F%2Fidenticons .github .com%62F6ba3c4d084aed0115087768b5619eee7 .pngér=x", "gravatar_id": "c747ffcd593aa4da922e8a7c4019d95b", "url": "https://api.github.com/users/gollam", "html_url": 
"https:/github.conygollum", "followers_url": "https:/api.github.cony/users/gollum/followers", "following_url": "https://api.github.comlusers/gollun/following{/other_user}", "gists_url": 
"https//api githab.convusers/gollum/gists{/gist_id}", "starred_url": "https/apiigithub.com/users/gollunystarred{/owner}{ repo}", "subseriptions_url": "httpsV/api github.com/users/eollum/subscriptions", 
“organizations_url": "htps://api.github.com/users/gollum/orgs", "repos_url": "htps:/api.github.conusers/gollumepos", "events_url": "https:/api github .com/users/gollunyevents{ /privacy}" 
"received_events_udl": "https://api.github.com/users/gollum/received_events’, "type": "Organization", "site_admin": false }, "private": false, "html_url": "https://github.com/gollum/gollum", "description": "A 
simple, Git-powered wiki with a sweet API and local frontend.", "fork": false, "url": "https:/api.github.com/repos/gollum/gollum", "forks_url": "https:/api.github.com/repos/gollun/gollum/forks", "keys_url": 
"https’/api.gihub.com/repos/gollum/gollum/keys{ /key_id}”, "collaborators_url': "https:/api.github.com/repos/gollum/gollun/collaborators{ /collaborator} ", "teams_url": 
"https//api.github.com/ropos/gollum/gollum/cams', "hooks_url": "https://api.github.com/repos/gollum/gollum/hooks", "issue_cvents_ud": "https://api github.com/repos/gollum/gollumlissucs/events{/number}", 
"events_url": "https://api.github.com/repos/gollum/gollum/events' rl": "https://api.github.com/repos/golium/gollum/assignees{ /user}", "branches_url": 
"https://api.github.com/repos/gollunygollum/branches{ /branch}", ttps//api github.com/repos/gollun/gollum/ags", "blobs_url": "https:/api.github.com/repos/gollum/gollum/givblobs{ /sha}", 
"git_tags_url": "https:/api github.com/repos/gollum/gollum/gititags{/sha}", "git_refs_url": "https://api.github.com/repos/gollum/gollun/givrefs{/sha}", "trees_url" 
"https:/api.github.com/repos/gollum/gollum/givtrees{/sha}", "statuses_url": "https:/api.github.com/repos/gollum/goliumstatuses/{ sha} ", "languages_url": "https://api.github.com/repos/gollum/gollum/languages" , 
url': "https://api.github.com/repos/gollum/gollum/stargazers", "contributors_url": "https://api github.com/repos/gollum/gollum/contributors" , "subscribers_url": 
.github.com/repos/gollum/gollum/subscribers", "subscription_url": "https://api.github.com/repos/gollum/gollum/subscription", "commits_url": 
i-github.com/repos/gollunygollum/commits{/sha}”, "git_commits_url": "https://api.github.com/repos/gollum/gollum/gitcommits{/sha}", "comments_url": 
ji.github.conyrepos/golium/gollun/comments{ /number}", "issue_comment_url": "https://api.github.com/repos/gollum/gollum/issues/comments/{number}", "contents_url" 
github con/repos/gollurmgollunn/eontents/{ +path}", "compare_url': "https://api.github.com/repos/gollam/gollunyeompare/{ base}...{head}", "merges_url": 

.github.com/repos/gollum/gollum/merges", "archive_url": "https://api.github.com/repos/gollum/gollum/{ archive_format}{ /ref}", "downloads_url": 
"https:/api.github.con/repos/gollun/gollun/downloads", "issucs_uzl': "https:/api.github.com/repos/gollum/gollun/issues{ /number}", "pulls_url": "https:/api.github.com/repos/gollun/gollum/pulls{ /number}", 
"milestones_url': "https:/api.github.com/repos/gollum/gollum/milestones{ /number}", "notifications_url": "https://api github .com/repos/gollum/gollum/notifications{ ?since,all,participating}", "labels_url": 
"https://api.github.com/repos/gollumgollum/iabels{ /name}", "releases_url": "https://api.github.comirepos/gollum/gollum/releases{ /id}", "created_at": "2010-03-29T18:30:53Z", "updated_at": "2014-01- 
16T15:42:052", "pushed_at": "2014-01-11T14:42:242", "git_url": "git//github.com/gollunygollum.git", "ssh_url": "git@github.com:gollum/gollum.git", "clone_url": "https://github.com/gollum/gollum.git", 
"svn_url": "httpsV/github com/gollam/gollum’, "homepage": ™, "size": 12109, "stargazers_count": 3979, "watehers._ count": 3979, "language": "JavaSeript", "has_issues": true, "has_downloads": true, "has_ wiki": 
true, "forks_count": 765, "mirror_url": null, "open_issues_count": 102, "forks": 765, "open_issues": 102, "watchers": 3979, "default_ branch": "master”, "master_branch": "master”, "organization": { "logine 
"gollum", "id": 3840027, "avatar_url": "https://eravatar.com/avatar/e747ffed593aa4da922e8a7c4019d95b?d=https93A %2F%2Fidenticons.github.com%2F6ba3c4d084aed01f5087768b5619ece7 pngéer=x", 
"gravatar_id": "c747ffed593aa4da922e8a7c4019d95b", "url": "https://api.github.com/users/gollam", "html_url": "https:/github.com/gollum", "followers_url": "https:/api.github.com/users/gollur/followers", 
"following_url": "https:/api.github.com/users/gollum/following{ /other_user}”, "gists_url": "https:/api,github.com/users/gollunygists{ /gst_id}", "starred_url": "https:/api.gitub.comf/users/gollum/starred{/owner} 
{/repo}", "subscriptions_url": "https://api.github.com/users/gollum/subscriptions", "organizations_url": "httpsy/api.github.comyusers/gollumlorgs', "repos_url": "https:/api.github.com/users/gollum/repos", 
"events_url": "https://api.github.com/users/gollum/events{ /privacy}", "received_events_url": "https://api.github .com/users/gollum/received_events", "type": "Organization", "site_admin": false }, "network_count': 
765, "subscribers_count": 175 } 





https://gravatar.com/avatar/c747ffcd593aa4da922e8a7c4019d95b? 














































































9-1: 完全 混乱 的 JSON 





显示 的 数据 好 多 啊 ! 虽然 AngularJS 的 JSON 过 滤器 会 以 精美 的 格式 把 数据 打印 出 来 ， 但 


是 这 也 有 点 太 多 了 。 接 下 来 修改 HIML， 去 掉 一 些 噪声 信息 。 


<htmL> 

<head> 

<title>CoffeeTe.ch</title> 

<meta name="Vviewport" content="width=device-width, initial-scale=1.0"> 


<Link rel="stylesheet" type="text/css" href="bootstrap.min.css"></Llink> 


</head> 

<body ng-app="coffeetech"> 

<div class="container" ng-controller="GithubCtrl"> 
<div>Subscriber count: {{ repo.subscribers count }}</div> 
<div>Network count: {{ repo.network_count }}</div> 
</div> 

<script 

src="angular.js"></script> 

<script src="github.js"></script> 

<script src="coffeetech.js"></script> 

</body> 

</htmL> 





我 们 可 以 修改 HIML， 只 显示 仓库 JSON 数据 中 的 几 个 重要 信息 。 此 处 显示 的 是 





subscriber_count 和 network_count。 现 在 看 到 的 页 面 整洁 一 些 了 ( 见 图 9-2 ) 。 








Subscriber count: 175 
Network count: 765 











图 9-2: 提取 所 关注 的 信息 


我 们 使 用 GitHub API 从 GitHub 托管 的 Gollum 仓库 中 提取 了 订阅 者 和 网 络 数 量 ， 然 后 把 


这 些 数据 放 到 了 单 页 应 用 中 。 


9.3.1 规划 应 用 的 数据 结构 





我 们 要 构建 的 是 一 个 咖啡 店 数据 库 ， 这 个 数据 库存 在 Git 中 ， 但 是 Git 及 相关 的 工具 ( 命 
令 行 工具 或 GitHub) 没有 提供 关系 型 数据 库 这 种 功能 。 因 此 ， 我 们 要 规划 一 种 结构 ， 让 存 














入 仓库 的 数据 易于 搜索 。 





这 个 应 用 用 于 搜索 咖啡 店 ， 而 咖啡 店 基本 都 在 大 城市 。 我 们 可 以 把 数据 存在 一 些 JSON 文 





件 中 ， 各 个 文件 使 用 城市 名 命名 ， 这 样 数据 就 与 城市 关联 起 来 了 ， 在 客户 端 可 以 使 用 地 理 





定位 功能 或 者 让 用 户 手动 选择 城市 ， 然 后 获取 相关 的 数据 。 





查看 GitHub 中 GitHub.js 的 文档 (https://github.com/michael/github) 之 后 得 知 ， 从 仓库 


中 获取 数据 可 以 使 用 一 些 选 项 。 我 们 将 把 数据 存 入 以 城市 名 命名 的 JSON 文 从 








F 中 ， 然 后 
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放 和 仓库 中 ， 再 从 那个 仓库 里 获取 数据 。 看 起 来 我 们 要 调用 github.getRepo( username， 
reponame ) 获取 仓库 对 象 ， 然 后 再 调用 repo.contents( branch, path, callback ) 。 























现在 应 用 有 个 骨架 了 ， 我 们 先 停 下 来 ， 确 保 构 建 出 的 应 用 易于 重 构 和 长 期 维护 。 这 意味 
着 ,我 们 要 在 项 目 中 添加 测试 。 








9.3.2 ”让 应 用 易于 测试 
测试 能 让 我 们 写 出 更 好 的 代码 ， 因 为 我 们 能 以 局 外 人 的 身份 思 芝 代码 该 怎么 使 用 ， 此 外 测 
试 还 能 让 外 人 (其 他 团队 成 员 ) 更 好 地 使 用 我 们 的 代码 。 测 试 能 促进 “社交 编程 ”。 








接 下 来 要 使 用 的 JavaScript 测试 工具 是 Karma。 这 个 工具 简化 了 JavaScript 单元 测试 的 编 
写 。 在 编写 测试 之 前 ， 先 要 安装 这 个 工具 。Karma 可 以 轻松 地 使 用 npm (安装 方法 参见 附 
录 B) 来 安装 。 











$ npm instaLL karma -9 
$ wget https://ajax.googleapis.com/ajax/libs/angularjs/1.2.7/angular-mocks.js 


使 用 angular-mocks.js 易于 在 测试 中 模拟 Angular 依赖 。 


然后 ， 新 建 一 个 文件 ， 将 其 命名 为 karma.config.js， 然 后 写 人 下 述 内 容 。 








module.exports = function(config) { 
config.set({ 
basePath: '', 
frameworks: ['jasmine'], 
files: [ ©@ 
'angular.js', 
'fixtures-*.js', 
'angular-mocks.js', 
'firebase-mock.js', 
'github.js', 
wx, js 
]， 
reporters: ['progress'], 
port: 9876, 
colors: true, 
LogLeveL: config.LOG_INFO, 
autoWatch: true, 
browsers: ['Chrome'], @ 
captureTimeout: 60000, 
singleRun: false 
]); 
}; 


这 与 Karma 的 默认 配置 差不多 。 


@ files 部 分 指定 JavaScript 实现 脚本 和 测试 脚本 的 加 载 顺 序 。 可 以 看 到 ， 我 们 明确 指定 
了 前 面 添 加 的 几 个 文件 ， 然 后 使 用 通配符 涵盖 余下 的 文件 。 
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@ 还 要 注意 ， 我 们 指定 的 测试 浏览 器 是 Chrome (因此 系统 中 要 有 )。 使 用 这 个 浏览 器 最 
好 ， 因 为 几乎 所 有 桌面 平台 都 支持 。 当 然 ， 如 果 你 想 让 Karma 在 Safari 或 Firefox 中 测 
试 ， 也 可 以 指定 这 两 个 浏览 器 。Karma 会 启动 各 个 指定 的 浏览 器 实例 ， 然 后 在 其 中 创 
建 测试 用 具 ， 运 行 测试 。 

写 测试 之 前 ， 要 大 清楚 想 让 代码 做 什么 。 


。 用 户 首次 访问 应 用 时 ， 使 用 浏览 器 的 地 理 定位 功能 确定 用 户 所 在 的 位 置 。 

。 从 仓库 中 获取 包含 各 个 城市 经 纬度 的 文件 。 

。 迭代 城市 列表 ， 检 查 用 户 是 否 在 这 些 城市 方圆 25 英里 的 范围 内 。 如 果 在 的 话 ， 那 就 把 
当前 城市 设 为 第 一 匹配 的 城市 。 

。 确定 所 在 城市 后 ， 从 GitHub 中 加 载 对 应 的 JSON 数据 。 


具体 而 言 ， 我 们 要 断言 能 加 载 有 两 个 城市 的 列表 ， 其 中 有 个 城市 名 为 Portland， 而 且 这 个 
城市 有 三 家 咖啡 店 。 


下 面 将 使 用 ng-init 指令 ， 其 作用 是 告诉 AngularJS 我 们 想 在 控制 器 加 载 完成 后 调用 指定 
的 函数 。 我 们 将 把 这 个 函数 命名 为 init。 下 面 来 测试 这 个 函数 。 


首先 要 使 用 Jasmine 测试 框架 为 AngularJS 应 用 的 测试 编写 设置 代码 。Jasmine 是 一 个 “ 行 
为 驱动 ”JavaScript 库 ， 提 供 了 用 于 组 织 和 创建 预期 行为 的 测试 函数 。Jasmine 框架 为 大 多 
数 常 见 的 断言 提供 了 “匹配 器 ”( 用 于 比较 预期 的 结果 和 函数 调用 的 返回 值 )， 如 果 没 有 合 
适 的 匹配 器 ， 那 么 还 能 自 定义 。 此 外 ，Jasmine 也 支持 为 国 数 创 建 “ 侦 件 ”， 即 截获 函数 调 
用 ,验证 调用 的 方式 是 否 符合 预期 。 通 过 具体 的 测试 最 能 体现 Jasmine 的 优雅 ， 下 面 我 们 
就 来 编写 测试 。 





EE 














































































































describe( "GithubCtrl", function() { 
var scope = undefined; © 
var ctrl = undefined; 
var gh = undefined; 
var repo = undefined; 
var geo = undefined; 


beforeEach( module( "coffeetech" ) ); @ 


beforeEach( inject( function ($controller, S$rootSscope ){®©® 
generateMockGeolocationSupport(); @ 
generateMockRepositorySupport(); 
scope = S$rootScope.$new(); © 
ctrl = $controller( "GithubCtrl", 
{ $scope: scope, Github: gh, Geo: geo } ); @ 


@ 在 函数 开头 定义 变量 。 如 果 不 这 么 做 ，JavaScript 会 在 初次 遇 到 变量 时 悄 无 声息 地 定义 ， 
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这 会 导致 变量 在 设置 代码 和 真正 的 测试 中 有 差异 。 

@ 在 beforeEach 国 数 中 调用 module 方法 加 载 coffeetech 模块 。beforeEach 国 数 中 的 代码 
会 在 各 个 测试 运行 之 前 执行 。 

@ AngularJS 使 用 inject 函数 把 $controller 和 $rootScope 对 象 提 供给 beforeEach 国 数 ， 
用 于 设置 测试 。 

@ 调用 两 个 函数 ， 创 建 测试 所 需 的 模拟 对 象 。 稍 后 讨论 这 两 个 函数 。 

日 按照 AngularJS 的 约定 ， 所 有 功能 和 状态 都 存储 在 scope 对 象 中 。 我 们 使 用 AngularJS 
提供 的 实用 函数 Srootscope.Snew() 新 建 一 个 scope 对 象 ， 并 把 它 的 引用 存储 在 一 个 变 
量 中 ， 以 便 测 试 代码 中 实现 的 真正 功能 。 

@ 传人 模拟 的 对 象 和 scope 对 象 ( 由 前 面 那 两 个 函数 调用 创建 )， 实 例 化 一 个 控制 器 对 象 。 
这 个 控制 器 使 用 scope 对 象 定义 函数 和 数据 ， 因 为 我 们 存储 了 scope 对 象 的 引用 ， 所 以 
可 以 调用 相关 的 函数 并 检查 数据 ， 断 言 实现 方式 是 正确 的 。 


接 下 来 ， 编 写 一 个 真正 的 测试 。 









































describe( "#init", function() { © 
it( "should initialize, grabbing current city", function() { @ 
scope.init(); © 
expect( geo.getCurrentPosition ).toHaveBeenCalled(); @ 
expect( gh.getRepo ).toHaveBeenCalled(); 
expect( repo.read ).toHaveBeenCalled(); 
expect( scope.cities.length ).toEquaL( 2 ); © 
expect( scope.city.name ).toEqual( "portland" ); 
expect( scope.shops.Length ).toEquaL( 3 ); 
}); 
]); 
]); 


@ describe 国 数 用 于 组 织 多 个 it 函数 中 定义 的 测试 。 此 处 测试 的 是 init 函数 ， 因 此 使 用 
#init 标识 符 是 合理 的 。 

@ describe 块 用 于 组 织 测 试 ， 而 让 块 用 于 指定 代码 来 运行 测试 。 

@ 控制 器 要 先 调用 init 函数 ， 因 此 我 们 在 测试 中 模拟 这 种 行为 ， 设 置 控制 器 的 状态 。 

@ 断言 代码 使 用 了 我 们 在 注入 的 对 象 上 定义 的 不 同 接口 : geo 对象 上 的 
getCurrentPosition， 以 及 仓库 对 象 上 的 read。 

日 接 下 来 ， 断 言 正确 加 载 了 数据 。 这 里 的 测试 验证 有 没有 两 个 城市 、 有 没有 加 载 默 认 城 

市 ， 以 及 默认 城市 的 名 字 是 不 是 等 于 字符 串 "portland"。 此 外 ， 测 试 还 验证 有 没有 为 

默认 城市 加 载 三 个 咖啡 店 。 在 实现 代码 中 ， 这 些 数据 从 JSON 文件 中 加 载 ， 不 过 我 们 关 

注 的 是 接口 和 数据 是 否 与 预期 相符 。 
































如 果 你 从 未 使 用 Jasmine 为 JavaScript 代码 写 过 测试 ， 一 开始 可 能 觉得 句法 有 点 难 懂 ， 其 
实 Jasmine 的 句法 很 优雅 ， 为 我 们 解决 了 大 量 问题 。 最 为 重要 的 一 点 是 ，Jasmine 提供 了 
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spyon 函数 ， 我 们 可 以 使 用 它 截获 函数 调用 ， 然 后 断言 函数 被 调用 了 。 只 要 在 测试 中 见 到 
toHaveBeenCalled()， 就 说 明 spyon 为 我 们 提供 了 一 个 断言 ， 用 于 确认 函数 被 调用 了 。 








现在 要 实现 对 上 述 测试 至 关 重 要 的 那 两 个 模拟 函数 。 把 这 两 个 国 数 放 在 beforeEach 


( module( "coffeetech" ) ) 那 行 和 beforeEach( inject( ... ) ) 函数 之 间 ， 让 Karma 能 
调用 它们 。 


beforeEach( module( "coffeetech" ) ); 


function generateMockGeolocationSupport( lat, lIng ){©@ 
response = ( lat && lng ) ? 
{ coords: { lat: lat, lng: lng } }: 
{ coords: CITIES[0] }; 
geo = { getCurrentPosition: function( success, failure ){@© 
success( response ); 


中 
spyOn( geo，"getCurrentPosition" ) .andCaLLThrough(); © 


function generateMockRepositorySupport() { @ 
repo = { read: function( branch, filenamne, cb ) { 日 
cb( undefined, 
JSON.stringify( filename == "cities.json" ? 
CITIES : PORTLAND ) ); 


}); 
spyon( repo, "read" ).andCallThrough(); 


gh = new Github({}); 
spyOn( gh, "getRepo" ).andCallFake( function() { @ 
return repo; 
3 
} 


beforeEach( inject( function ($controller, S$rootScope ) { 


@ 首先 实现 generateMockLocation 国 数 。 

@ 为 了 模拟 位 置 ， 我 们 要 创建 一 个 geo 对 象 ， 而 且 要 在 这 个 对 象 上 定义 getCurrentPosition 
国 数 ， 这 个 国 数 在 成 功 执行 时 调用 success 回调 。 这 个 过 程 与 浏览 器 原生 支持 的 地 理 定 
位 功能 完全 一 样 ， 也 定义 了 相同 的 函数 。 

@ 然后 ， 调 用 spyon 为 getCurrentposition 函数 创建 侦 件 。 这 样 才能 在 测试 中 断言 
getCurrentPosition 国 数 被 调用 了 。 

@ 接 下 来 ， 实 现 generateMockRepositorySupport 国 数 。 

@ 同样 ， 我 们 要 定义 一 个 模拟 对 象 ， 不 过 这 一 次 要 在 对 象 上 定义 read 方法 。 这 个 方法 的 
作用 与 JavaScript GitHub.js 库 提 供 的 API 中 的 同名 方法 一 样 。 与 前 面 的 模拟 一 样 ， 我 
们 调用 spyon 为 read 方法 创建 侦 件 ， 这 样 才 能 在 测试 中 断言 read 方法 被 调用 了 。 可 
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是 ，repo 不 是 “顶层 ”对 象 ， 而 是 调用 getRepo 方法 得 到 的 对 象 。 因 此 ， 要 让 getRepo 
调用 返回 这 个 模拟 对 象 。 
@ 为 getRepo 方法 创建 侦 件 ， 返 回 模拟 的 仓库 对 象 。 调 用 read 方法 获取 信息 时 使 用 的 其 
实 是 这 个 对 象 。 























写 好 测试 之 后 ， 在 命令 行 中 运行 测试 组 件 ， 会 看 到 测试 失败 。 





$ karma start karma.conf.js 
Chrome 32.0.1700 (Mac OS X 10.9.1) GithubCtrl #init should initialize, 
grabbing current city FAILED 
Error: [$injector:modulerr] Failed to instantiate module...: 
Error: [$injector:nomod] Module 'coffeetech' is not available! 
You either misspelled the module name or forgot to Load it. 
If registering a module ensure that you specify the 
dependencies as the second argument . 


接 下 来 要 提供 一 些 测试 固件 (fixture)。 





9.3.3 测试 数据 
我 们 要 提供 固件 ， 即 存储 测试 数据 的 文件 。 在 保存 其 他 代码 的 目录 中 新 建 fxtures-cities.js 
文件 ， 写 入 下 述 内 容 。 
































var CITIES = [{ 
name: "portland", 
latitude: 45, 
longitude: 45 

$F: 
name: "seattle", 
latitude: 47.662613, 
longitude: -122.323837 

}] 





再 新 建 fixtures-portland.js 文件 ， 写 入 下 述 内 容 。 


var PORTLAND = [{ 
"name": "Very Good Coffee Shop", 
"latitude": 45.52292, 
"Longitude": -122.643074 

nt 
"name": "Very Bad Coffee Shop", 
"latitude": 45.522181, 
"Longitude": -122.63709 

}, { 
"name": "Mediocre Coffee Shop", 
"latitude": 45.520437, 
"longitude": -122.67846 

3}] 
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9.3.4 
接 下 来 ， 
mod 


}); 


mod. 


}] 


mod. 


3 


mod. 


修改 coffeetech.js 文 件 





添加 coffeetech.js 文件 。 现 在 只 关注 设置 代码 和 对 init 函数 的 改动 。 


mod = anguLar.moduLe( 'coffeetech', [] ); 


.factory( 'Github', ，function() { // 


return new Github({}); 


factory( 'Geo', [ '$window', function( S$Swindow ) { // @ 
return S$window.navigator .geolocation; 


) 


factory( 'Prompt', [ 'S$window', function( Swindow ) { 
return S$window.prompt; 


); 


controller( 'GithubCtrl', [ '$scope', 'Github', 'Geo', 'Prompt'" 


function( S$scope, ghs, Geo, Prompt ) { 
$scope.messages = [] 


$scope.init = function() { // ©@ 
$scope.getCurrentLocation( function( position ) { 
$scope.latitude = position.coords.latitude; 
$scope. longitude = position.coords.longitude; 
$scope.repo = ghs.getRepo( "xrd", "spa.coffeete.ch" ); 
$scope.repo.read( "gh-pages", "cities.json", 
function(err, data) { // O 
$scope.cities = ]SON.parse( data ); //© 
// 确认 当前 城市 
$scope.detectCurrentCity(); // ©@ 








// 如 果 确 定 了 所 在 城市 ,获取 那个 城市 
if( $scope.city ) { 
$scope.retrieveCity(); 


} 


$scope.$apply(); // © 
}); 
}); 








// ©@ 


// © 


@ 提取 GitHub 库 ， 放 入 一 个 AngularJS 工厂 方法 中 。 这 样 便 能 把 模拟 的 GitHub 对 和 象 注 入 


到 测试 中 。 如 果 把 创建 GitHub 实例 的 代码 放 在 控制 器 
@ 提取 地 理 定位 功能 ， 放 入 一 个 AngularJS 工厂 方法 中 。 与 GitHub 库 一 样 ， 这 检 











向 测试 注入 模拟 的 对 象 。 
@ 我 们 重新 定义 了 控制 器 ,注入 所 需 的 各 个 对 象 。 我 们 提取 出 了 GitHub API 对 象 和 


Geo 对 象 ， 让 二 者 变 成 依赖 ， 而 这 个 句法 能 找到 正确 的 对 象 ， 并 


下 














里 ， 在 测试 中 无 法 轻易 模拟 。 


做 可 以 





把 它们 提供 给 控制 


器 。 此 外 ， 你 可 能 广 意 到 了 ， 这 一 次 创建 控制 器 的 句法 稍微 有 点 不 同 ， 我 们 使 用 的 是 
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controller( "CtrlName", [ 'dependency1', 'dependency2', function( dependency1， 
dependency2 ) 人 ] )。 使 用 这 种 写法 ， 即 使 简化 了 JavaScript 代码 ， 代 码 也 依然 可 用 ， 
而 前 面 那 种 写法 在 简化 后 就 失效 了 ， 因 为 AngularJS 找 不 到 依赖 的 名 称 。 

@ 把 功能 放 入 init 函数 中 ， 这 样 就 能 在 测试 中 调用 了 。 

日 设置 用 户 名 ， 然 后 加 载 仓 库 。 如 果 使 用 自己 的 仓库 ， 那 么 要 相应 地 做 出 修改 ， 否 则 就 
继续 使 用 这 两 个 参数 。 

@ 使 用 read 方法 读 取 仓 库 中 文件 的 内 容 。 注 意 ， 这 里 使 用 的 是 gh-pages 分 支 ， 因 为 单 页 
应 用 和 所 有 数据 都 存在 这 个 分 支 中 。 

@ 获取 到 的 数据 只 是 一 个 字符 串 ， 要 使 用 JSON.parse 方法 将 其 转换 成 JavaScript 对 象 。 

从 仓库 中 获取 数据 之 后 ， 可 以 使 用 城市 数组 中 的 数据 确认 当前 城市 。 

@ 因为 我 们 在 AngularJS 之 外 调用 ， 而 且 在 回调 中 返回 ， 所 以 要 像 前 面 的 示例 那样 调用 
scope.$apply()。 

































































© 




















接 下 来 可 以 实现 地 理 编码 功能 


9.4 添加 地 理 编 码 功 能 

我 们 要 定义 几 个 函数 ， 从 GitHub API 中 获取 城市 数据 ， 使 用 浏览 器 的 地 理 定位 功能 找到 用 
户 所 在 的 位 置 ， 使 用 用 户 的 当前 位 置 确定 他 们 离 哪个 城市 最 近 ， 计 算 距 离 ， 确 定 最 近 的 城 
市 后 加 载 那 座 城市 的 数据 ， 最 后 再 定义 一 个 国 数 查 询 用 户 的 GitHub 凭据 ， 然 后 为 数据 添 
加 评注 。 


首先 ， 实 现 加 载 城市 数据 的 函数 。 














$scope.retrieveCity = function() { © 
$scope.repo.read( "gh-pages", $scope.city.name + ".json", 
function(err, data) { 
$scope.shops = JSON.parse( data ); 
$scope.$apply(); 
}); 
} 


$scope.loadCity = function( city ){@ 
$scope.repo.read( "gh-pages", city + ".json", function(err, data) { 
$scope.shops = JSON.parse( data ); 
$scope.$apply(); 
})3 


@ retrieveCity 函数 从 仓库 对 象 中 读 取 咖 啡 店 列表 ， 方式 与 获取 城市 列表 一 样 。 把 数据 
载 入 作用 域 中 之 后 ， 调 用 $apply()， 通 知 Angular。 


@ LoadCity 加 载 城市 名 对 应 的 城市 数据 。 
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接 下 来 实现 计算 当前 用 户 与 各 城市 间距 离 的 函数 。 





$scope.getCurrentLocation = function( cb ) {( @ 
if( undefined != Geo ) { 
Geo .getCurrentPosition( cb, $scope.geolocationError ); 
} elsef{ 
console.error('not supported'); 
} 
}; 


$scope.geolocationError = function( error ) {@ 
console.log( "Inside failure" ); 


}; 


$scope.detectCurrentCity = function() { © 

// 计算 两 个 位 置 之 间 的 距离 ,以 此 确定 

// 离 方圆 25 英 里 内 的 哪 座 城市 最 近 

for( var i = 0; i < $scope.cities.length; i++ ) { 

var dist = $scope.calculateDistance( $scope.latitude, @ 

$scope.longitude, 
$scope.cities[i].latitude, 
$scope.cities[i].longitude ); 




















if( dist < 25 ) { 
$scope.city = $scope.cities[i]; 
break; 


} 


toRad = function(VaLue) { © 
return Value * Math.PI / 180; 


}; 

$scope.calculateDistance = function( Latitude1， ©@ 
Longitude1， 
Latitude2 ， 


longitude2 ) { 

R = 6371; 

dLatitude = toRad(Latitude2 - latitudel); 

dLongitude = toRad(Longitude2 - Longitude1); 

Latitude1 = toRad(Latitude1) ; 

latitude2 = toRad(Latitude2); 

a = Math.sin(dLatitude / 2) * Math.sin(dLatitude / 2) + 
Math.sin(dLongitude / 2) * Math.sin(dLongitude / 2) * 
Math.cos(latitude1) * Math.cos(latitude2); 

c= 2* Math.atan2(Math.sqrt(a), Math.sqrt(1 - a)); 

dR ES 

return d; 


@ 定义 代码 中 将 调用 的 getCurrentLocation 函数 。 我 们 在 注入 的 Geo 对象 上 调用 
getCurrentPosition 函数 来 实现 这 个 函数 (在 测试 中 要 使 用 模拟 的 函数 ， 因 此 在 真正 的 
代码 中 要 在 浏览 器 原生 接口 的 基础 上 抽象 ) 。 
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@ 我 们 要 为 getCurrentPosition 调用 提供 处 理 错误 的 回调 ， 这 里 实现 的 就 是 这 个 回调 ， 
它 把 错误 输出 到 控制 台 。 

@ 然后 ， 定 义 detectCurrentCity 国 数 ， 遍 历 城市 列表 ， 检 查 是 否 在 某 座 城市 中 。 

@ 夺 代 城市 列表 ， 计 算 当 前 位 置 是 否 离 哪 座 城 市 的 距离 小 于 25 英里 。 各 个 城市 都 有 经 纬 
度数 据 。 找 到 离 得 最 近 的 城市 后 ， 把 那 座 城市 设 为 当前 城市 ， 然 后 退出 循环 。 

@ 为 了 计算 距离 ， 需要 一 个 弧度 转换 函数 。 

@ 最 后 ， 定 义 计算 距离 的 函数 。 


























一 开始 是 不 是 觉得 计算 距离 的 函数 有 点 难怪 ”我 读 过 一 篇 文章 之 后 才 写 出 了 这 些 代码 。 那 
篇 文章 介绍 了 如 何 使 用 PostgreSQL 数据 库 中 存储 的 过 程 (procedure) 做 地 理 编码 ， 我 把 那 
些 代 码 转 成 JavaScript 了 。 如 果 不 是 地 理 编码 专家 ， 如 何 确 定 这 些 代 码 是 正确 的 呢 ? 好 吧 ， 
我 们 编写 儿 个 测试 检查 一 下 。 把 下 面 几 行 代码 添加 到 coffeetech.spec.js 文件 的 末尾 ， 放 在 
最 后 一 对 结束 括号 }); 内 。 






































describe( "#calculateDistance", function() { 
it( "should find distance between two points", function() { 
expect( parseInt( 
scope.calculateDistance( 14.599512， 
120.98422， 
10.315699 ， 
123.885437 ) * 0.61371 ) ). 
toEquaL( 354 ); 
]); 
5 


为 了 编写 这 个 测试 ， 我 在 Google 中 搜索 了 “distance between Manila”，Goosgle 使 用 
“Cebu” 自 动 补 全 了 我 的 搜索 词 条 。Google 给 出 的 距离 是 338 英里 。 然 后 ， 我 查 出 了 这 
两 座 城市 的 经 纬度 ， 写 出 了 上 述 测 试 。 我 预计 测试 会 失败 ， 因 为 根据 坐标 计算 出 的 英里 
数 多 少 会 差 一 点 。 可 是 ， 测 试 表明 两 座 城市 距离 为 571。 奇 怪 ， 难 道 单位 是 千 米 而 不 是 英 
里 ?确实 ,我 忘 了 这 种 算法 计算 的 是 千 米 距离 ， 而 不 是 英里 。 因 此 ， 我 们 要 把 结果 乘 以 
0.621371 才能 得 到 英里 数 。 最 终 的 结果 与 Google 给 出 的 距离 相差 无 几 。 


城市 数据 


我 们 要 为 应 用 提供 一 些 可 用 的 数据 。 把 下 述 内 容 写 入 cities.json 文件 。 





















































[ 

{ 
"longitude": -122.67620699999999 ， 
"latitude": 45.523452 ， 
"name": "portland" 

二 

{ 
"Longitude": -122.323837， 





A 
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"Latitude": 47.662613 ， 
"name": "seattle" 
} 
] 


至 此 ， 我 们 实现 了 地 理 编码 功能 ， 还 提供 了 示例 数据 。 接 下 来 要 询问 用 户 的 登录 凭据 了 。 


9.5 添加 登录 功能 


如 果 有 人 想 派生 GitHub 中 的 仓库 ， 那 么 必须 登录 GitHub。 因 此 ， 要 让 用 户 输入 登录 凭据 。 








$scope.annotate = function() { 
User = Prompt( "Enter your github username" ) 
password = Prompt( "Enter your github password" ) 
data = Prompt( "Enter data to add" ); 

}; 


现在 ， 要 像 下 面 这 样 在 index.html 文件 中 显示 这 些 新 数据 (省略 了 HITML 文件 中 肯定 都 有 
的 部 分 ) 。 





<body ng-app="coffeetech"> 

<div class="container" ng-controller="GithubCtrl" ng-init="init()"> 
<h1>CoffeeTe.ch</h1> 

<h3 ng-show="city">Current city: {{city.name}}</h3> 


<div class="row"> 

<div class="col-md-6"><h4>Shop Name</h4> </div> 
<div class="col-md-6"><h4>Lat/Lng</h4> </div> 
</div> 

<div class="row" ng-repeat="shop in shops"> O 
<div class="col-md-6"> 加 

{{ shop.nane }} © 

</div> 

<div class="col-md-6"> {{ shop.latitude }} / {{ shop.longitude }} </div> 
</div> 

</div> 


@ ng-repeat 是 AngularJS 提供 的 指令 ， 用 于 迭代 数组 中 的 元 素 。 这 里 ， 我 们 使 用 这 个 指 
令 迄 代 portland.json 文件 中 的 元 素 ， 然 后 使 用 各 次 返 代 从 元 素 中 获取 的 数据 插入 一 段 
HTML. 

@ 使 用 Bootstrap 编写 HTML 结构 很 简单 。col-md-6 类 告诉 Bootstrap， 创 建 一 个 占 12 栏 
布局 (Bootstrap 默认 的 布局 方式 ) 一 半 宽 度 的 分 栏 。 我 们 使 用 这 种 方式 并 排放 置 了 两 
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栏 。 如 果 在 移动 设备 中 访问 ， 这 两 栏 可 能 会 纵向 合 放 。 
@ 使 用 AngularJS 的 双向 数据 绑 定 句法 插入 咖啡 店 的 名 字 。 


出 错 了 吗 

在 浏览 器 中 打开 这 个 应 用 ， 不 会 看 到 我 们 所 在 城市 中 的 咖啡 店 。 这 说 明 什 么 地 方 出 错 
了 ， 我 们 来 调查 调查 。 我 推荐 使 用 Chrome 浏览 如 调试 ， 不 过 也 可 以 使 用 你 喜欢 的 训 览 器 
和 开发 者 工具 。 如 果 使 用 的 是 Chrome， 那 就 在 页 面 中 的 任意 位 置 点 击 鼠 标 右键 ， 在 弹出 
菜单 的 底部 选择 “Inspect Element”( 审 查 元 素 ) (也 可 以 按键 盘 上 的 F12 快捷 键 ， 或 者 在 
Windows 和 Linux 中 按 Ctrl-Shift-I 键 ， 在 Mac 中 按 Cmd-OptI 键 )， 打 开 开 发 者 控制 台 。 
然后 ， 选 择 控制 台 标 签 页 。 刷 新 浏览 器 窗口 ， 你 会 在 控制 台中 看 到 : 























Uncaught TypeError: Cannot call method 'select' of undefined 


点 击 右 侧 的 GitHub.js， 会 看 到 如 图 9-3 所 示 的 错误 。 
































x Elements Resources Network |Sources| Timeline Profiles Audits Console AngularJs Rails 
对 | github.js x | coffeetech.js 
TEqUESTt GCT /Tepouratm T /YIUUUWOVS/ + SMady TU COs raw Jy 
324 }; 
325 
326 // For a given file path, get the corresponding sha (blob for files, tree for dirs) 
327 Wk. 
328 
329 this,getSha = function(branch, path, cb) { 
330 // Just use head if path is empty 
331 if (path === "") return that.getRef("heads/"+branch, cb); 
332 that.getTree(branch+"?recursive=true", function(err, tree) { 
333 if (err) return cb(err); 
334 | var file = _,.select(tree, function(file) { 
335 return file.path === path; 
336 }) [0]; 
33T cb(null, file ? file,.sha : null); 
338 于 
339 }; 
340 
341 // Retrieve the tree a commit points to 
342 // -----—— 











9-3: 意料 之 外 的 错误 


可 以 看 到 ， 这 个 错误 是 树 对 象 上 的 select 方法 导致 的 。 这 个 方法 在 下 划 线 符号 上 定义 。 如 
果 经 常 使 用 JavaScript， 你 会 意识 到 下 划 线 变量 出 自 Underscore 库 ， 而 select 方法 的 作用 
是 获取 数组 中 满足 条 件 的 第 一 个 元 素 。 根 据 GitHub.js 库 的 实现 ， 它 会 获取 仓库 的 整个 树 对 
象 ， 然 后 进 代 其 中 的 各 个 元 素 ， 选 择 匹 配 请 求 文件 名 的 文件 。 这 是 需要 考虑 的 重要 性 能 因 
素 。GitHub API 没有 提供 直接 使 用 路 径 名 请 求 内 容 的 方式 ， 我 们 要 先 获 取 文 件 列表 ， 然 后 
再 使 用 SHA 散 列 值 请 求 文件 。 这 个 过 程 分 两 步 ， 要 调用 API 两 次 (可 能 会 用 很 长 时 间 )。 














怎样 修正 未 定义 select 方法 的 错误 呢 ? 是 不 是 忘记 引入 underscore.js 库 了 ? 根据 GitHub.js 
文档 ， 它 需要 使 用 underscore.js 和 base64.js。 我 们 忘记 引入 这 两 个 库 了 。 真 是 失误 ! 为 了 
引入 这 两 个 库 ， 先 在 控制 台中 执行 下 述 命 令 。 
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$ wget http://underscorejs.org/underscore-min.js 
$ wget https://raw.github.com/dankogai/js-base64/master/base64.js 


然后 把 这 两 个 库 添 加 到 index.html 文件 中 。 最 终 ， 引 入 JavaScript 文件 的 元 素 如 下 。 


<script src="angular.js"></script> 
<script src="underscore-min.js"></script> 
<script src="base64.min.js"></script> 
<script src="github.js"></script> 

<script src="coffeetech.js"></script> 


现在 可 以 添加 一 些 虚 拟 数据 ， 规 划 用 户 提供 的 数据 采用 什么 结构 。 


9.6 显示 “即将 ) 由 用 户 提供 的 数据 


目前 ， 我 们 构建 了 存储 城市 和 城市 中 咖啡 店 的 数据 库 。 可 是 ，Google 地 图 或 Apple 地 图 
已 经 提供 了 这 些 人 信息。 不过， 如果 在 此 基础 上 添加 额外 的 信息 〈 例 如 关于 咖啡 店 的 奇怪 信 
息 ) ， 那 么 用 户 使 用 他 们 最 爱 的 地 图 应 用 寻找 咖啡 店 时 可 能 会 用 得 上 。 


首先 添加 一 些 关于 咖啡 店 的 虚拟 数据 。 新 建 portland.json 文件 ， 写 入 下 述 内 容 。 





























[ 
{ 
"information" : [ 
"offers gluten free desserts", 
"free wifi", 
"accepts dogs" 
]， 
"Longitude" : -122.643074， 
"latitude" : 45.52292, 
"name" : "Very Good Coffee Shop" 
}, 
{ 
"Latitude" : 45.522181, 
"name" : "Very Bad Coffee Shop", 
"Longitude" : -122.63709 
}, 
{ 
"name" : "Mediocre Coffee Shop", 
"Latitude" : 45.520437， 
"Longitude" : -122.67846 
} 
] 


注意 ， 我 们 在 数据 集中 添加 了 一 个 名 为 information 的 数组 。 使 用 这 个 数组 便于 搜索 。 在 
index.html 文件 中 添加 搜索 功能 。 
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<div class="container" ng-controller="GithubCtrl" ng-init="init()"> 


<h1>CoffeeTe.ch</h1> 
<input styLe=" width: 20em;" ng-model="search" 
placeholder="Enter search parameters..."/> © 


<h3 ng-show="city">Current city: {{city.name}}</h3> 


<div class="row="> 

<div class="col-md-6"><h4>Shop Name</h4> </div> 

<div class="col-md-6"><h4>Lat/Lng</h4> </div> 

</div> 

<div class="row" ng-repeat="shop in shops | filter:search"> 名 
<div class="col-md-6"> 

{{ shop.name }} 


<div ng-show="search"> © 

<span ng-repeat="info in city.information"> 

<span class="label label-default">city.data</span> 
</span> 

</div> 


</div> 

<div class="col-md-6"> 

<a target=" map" @ 
href="http://maps.google.com/?q={{shop.latitude}},{{shop.longitude}}"> 
Open in map ({{shop.latitude}},{{shop.longitude}}) 

</a> 

</div> 





@ 添加 一 个 搜索 框 ， 绑 定 到 作用 域 中 的 search 模型 上 。 

@ 为 数据 添加 一 个 过 滤器 ， 显 示 在 shops 数组 中 搜索 得 到 的 各 个 元 素 。 
@ 搜索 时 (定义 模型 变量 search) 显示 额外 的 信息 。 

@ 使 用 经 纬度 信息 指向 Google 地 图 中 对 应 的 页 务 

















o 








现在 ， 如 果 在 搜索 框 中 输入 “gluten”， 那 么 只 会 显示 匹配 词 条 的 咖啡 店 ， 而 且 额 外 的 信息 
以 标注 的 形式 显示 在 店名 下 面 ( 见 图 9-4)。 


























CoffeeTe.ch 


|giuten | 





Current city: portland 


Shop Name Map Link 
Very Good Coffee Shop Open in map (4 


pry Cr Er 











图 9-4: 使 用 “gluten” 词 条 过 滤 咖 啡 店 


用 户 贡 献 的 数据 
现在 应 用 可 以 正常 运行 了 ， 下 面 我 们 要 让 用 户 添加 信息 ， 帮 我 们 构建 数据 库 。 我 们 将 在 地 
图 链接 下 方 添加 一 个 按钮 ， 让 用 户 为 咖啡 店 添加 额外 的 信息 。 


若 想 贡献 信息 ， 用 户 要 派生 仓库 ， 改 动 之 后 向 源 仓库 发 起 拉 取 请 求 。 派 生 是 指 在 GitHub 
账户 中 存 一 份 源 仓 库 的 副本 。 这 些 步骤 在 这 个 Web 应 用 中 都 能 使 用 GitHub.js 库 实现 。 当 
然 ， 如 果 有 人 想 派 生 仓库 到 自己 的 账户 中 ， 那 就 必须 登录 ， 因 此 要 让 用 户 输入 用 户 名 和 密 
码 。 如 果 你 觉得 在 Web 应 用 中 让 用 户 提供 GitHub 凭据 不 安全 ， 先 别 急 ， 稍 后 我 们 会 使 用 
安全 的 方式 实现 这 个 功能 。 


首先 ， 要 在 HTML 中 添加 annotate 按钮 。 






































<button ng-click="annotate(shop)">Add factoid</button> 
然后 ， 编 写 儿 个 测试 。 新 建 coffeetech.annotate.spec.js 文件 ， 写 入 下 述 内 容 。 
describe( "GithubCtrl", function() { 


var scope = undefined, gh = undefined, 
repo = undefined, prompter = undefined; 


function generateMockPrompt() { 
prompter = { prompt: function() { return "ABC" } }; © 
spyon( prompter, "prompt" ).andCallThrough(); 


} 


var PR_ID = 12345; 
function generateMockRepositorySupport() { © 
repo={ 
fork: function( cb ) { 
cb( false ); 
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}， 
write: function( branch, filename, data, commit msg, cb ) { 
cb( false ); 


createpullRequest: function( pull, cb ) { 
cb( false, PR_ID ); 
和 
read: function( branch, filename, cb ) { 
cb( undefined, 
JSON.stringify( filename == "cities.json" ? 
CITIES : PORTLAND ) ); 


spyOn( repo, "fork" ).andCallThrough(); 
spyOn( repo, "write" ).andCallThrough(); 
spyOn( repo, "createpPullRequest" ).andCallThrough(); 
spyOn( repo, "read" ).andCallThrough(); 


gh = { getRepo: function() {} }; © 
spyOn( gh, "getRepo" ).andCallFake( function() { 


return repo; 


); 
ghs = { create: function() { return gh; } }; 





这 与 前 面 的 测试 类 似 ， 我 们 模拟 了 GitHub.js 库 中 的 几 个 对 象 。 











@ 模拟 提示 功能 。 我 们 将 使 用 浏览 器 内 置 的 提示 机 制 提示 用 户 输入 用 户 名 、 密 码 和 评 广 
数据 。 

@ 为 模拟 的 GitHub 对 象 添 加 三 个 新 方法 : fork、write 和 createPuLLRequest。 然 后 验证 
有 没有 调用 这 三 个 方法 。 

@ 调用 getRepo 函数 时 ， 我 们 想 通 过 侦 件 确认 的 确 调 用 了 ， 不 过 我 们 还 想 返 回 为 测试 提供 
虚拟 的 仓库 对 象 ， 因 此 要 使 用 这 个 句法 。 








我 们 要 在 beforeEach 函数 中 添加 设置 代码 ， 为 测试 加 载 模 拟 的 对 象 ， 并 且 创 建 控 制 器 和 作 
用 域 。 





var $timeout; //©@ 
beforeEach( inject( function ($controller, $rootScope, $injector ) { 
generateMockRepositorySupport(); // @ 
generateMockPrompt(); 
$timeout = $injector.get( '$timeout' ); // 日 
scope = $rootScope. $new(); 
ctrl = $controller( "GithubCtrl", 
{ $scope: scope, 
Github: ghs, 
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"Stimeout ' : $timeout, 
"Swindow' : prompter } ); 


} ) ); 


@ 根据 GitHub.js 库 中 fork 方法 的 文档 ， 它 要 花 点 时 间 才 能 返回 (GitHub 要 花 时 间 完 成 
派生 请 求 ， 具 体 多 久 不 好 确定 )， 因 此 要 在 应 用 中 设置 超时 时 间 ， 然 后 请 求 新 仓库 。 使 
用 AngularJS 时 ， 可 以 模拟 一 个 可 编程 的 超时 界面 ， 这 样 便于 在 测试 中 控制 。 

@ 生成 模拟 的 GitHub 方法 调用 和 侦 件 ， 然 后 生成 模拟 的 提示 功能 。 








@ 前 
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面 说 过 ， 我 们 要 获取 $timeout 变量 ， 使 用 这 个 方法 可 以 从 injector 对 象 上 获取 


AngularJS 为 测试 提供 的 模拟 超时 时 间 。 


接 下 来 ， 为 annotate 国 


国 数 编写 测试 。 





describe( "#annotate", function() { © 


it( "should 


annotate a shop", function() { 


scope.city = PORTLAND 
var shop = { name: "A coffeeshop"” } 
scope.annotate( shop ); 名 


expect( 
expect( 
expect( 
expect( 


expect( 
expect( 


scope.shopToAnnotate ).toBeTruthy(); © 
prompter .prompt.calls.length ).toEquaL( 3 ); 
scope.username ).not.toBeFalsy(); 
scope.annotation ).not.toBeFalsy(); 


repo.fork ).toHaveBeenCalled(); @ 
scope.waiting.state ).toEqual( "forking" ); © 


$timeout.flush(); @ 


expect( 
expect( 
expect( 
expect( 
expect( 


scope.forkedRepo ).toBeTruthy(); @ 

repo.read ) .toHaveBeenCalled(); 

repo.write ).toHaveBeenCalled(); 
repo.createpullRequest ).toHaveBeenCalled(); 
scope.waiting.state ).toEqual( "annotated" ); 


$timeout.flush(); @ 


expect( 


}); 
3 


scope.waiting ) .toBeFaLsy(); 














9 ey describe 块 ， 将 其 命名 为 #annotate， 用 于 组 织 相关 的 测试 。 然 后 ， 实 现 一 个 
国 数 ， 把 描述 信息 设 为 “annotate a shop”。 我 们 只 会 编写 这 一 个 测试 。 
@ 设置 好 前 置 条 件 之 后 ，scope 对 象 应 该 有 个 选中 的 城市 ， 然 后 创建 一 个 咖啡 店 ， 再 调用 
annotate 方法 为 咖啡 店 添加 评注 。 
@ 调用 annotate 方法 之 后 ， 代 码 应 该 请 求 GitHub API 的 登录 凭据 ， 然 后 让 用 户 提供 对 咖 
啡 店 的 评注 。 在 浏览 器 中 ， 这 个 过 程 会 出 现 三 个 提示 。 测 试 模拟 了 prompt 对 象 ， 因 此 
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应 该 调用 模拟 的 prompt 对 象 三 次 。 此 外 ， 我 们 还 验证 了 scope 对 象 应 该 具有 的 几 个 状 
态 ， 例 如 供 后 面 使 用 的 用 户 名 和 评注 。 

@ 然后 ，GitHub API 应 该 执行 第 一 个 调用 : GitHub.js 应 该 请 求 派生 仓库 。 

随后 应 该 进入 等 待 状态 。UI 会 使 用 scope.waiting.state 通知 用 户 ， 我 们 正在 等 待 。 

@ 模拟 派生 完成 的 超时 时 间 结 束 后 ， 我 们 会 看 到 代码 在 作用 域 中 存储 了 派生 仓库 得 到 的 

结果 。 

@ 接 下 来 ， 验 证 GitHub API 调用 了 添加 评注 的 方法 。 

@ 再 次 调用 fush() 让 超时 时 间 结 束 。 最 后 ， 全 部 结束 之 后 ， 应 该 告诉 用 户 不 再 处 于 等 待 
状态 了 。 


如 果 后 全 还 运行 着 Karma， 会 看 到 测试 失败 ， 输 出 下 述 消息 : 























© 


























Chrome 32.0.1700 (Mac OS X 10.9.1) GithubCtrl #annotate should 
annotate a shop FAILED 
TypeError: Object #<Scope> has no method 'annotate 
at null.<anonymous> (/.../coffeetech.spec.js:80:19) 











接 下 来 ， 我 们 要 在 coffeetech.js 文件 中 实现 这 个 功能 。 在 文件 的 末尾 ， 结 束 花 括 号 之 前 添 
加 下 面 几 行 代码 。annotate 函数 其 实 做 了 两 件 事 : 派生 仓库 到 用 户 名 下 ， 等 派生 结束 后 ， 
使 用 GitHub API 在 派生 的 仓库 中 添加 评注 信息 。 








Sl 





$scope.annotate = function( shop ) {©@ 
$scope.shopToAnnotate = shop; 
$scope.username = S$Swindow.prompt( "Enter your github username (not email!)" ) 
pass = S$window.prompt( "Enter your github password" ) 
$scope.annotation = S$window.prompt( "Enter data to add" ); @ 
gh = ghs.create( $scope.username, pass ); © 
toFork = gh.getRepo( "xrd", "spa.coffeete.ch" ); @ 
toFork.fork( function( err ) { 
if( !err ) {© 
$scope.notifyWaiting( "forking", 
"Forking in progress on GitHub, please wait" ); @ 
$timeout( $scope.annotateAfterForkCompletes, 10000 ); @ 
$scope. $apply(); 


} ); 
}; 


@ 首先 ， 定义 annotate 函数 。 参 照 测试 ， 这 个 函数 应 该 接收 一 个 shop 对 象 作为 参数 ， 评 
注 添 加 到 这 个 对 象 上 。 

@ 提示 用 户 三 次 ， 分 别 让 用 户 输入 GitHub 的 用 户 名 和 密码 ， 以 及 评注 的 文本 。 如 果 你 觉 
得 这 样 做 很 不 受 ， 别 担心 ， 稍 后 会 修改 。 
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使 用 用 户 输入 的 用 户 名 和 密码 创建 一 个 GitHub 对 象 。 对 拼写 不 对 或 错误 凭据 的 处 理 留 
作 练 习 交 给 读者 完成 。 
使 用 GitHub.js 库 提供 的 getRepo 国 数 可 以 创建 仓库 对 象 〈 在 本 地 创建 对 现 有 仓库 的 引 
用 )。 有 了 仓库 对 象 之 后 ， 可 以 调用 fork 方法 派生 仓库 。 

即便 没有 错误 ， 也 要 意识 到 派生 操作 所 需 的 时 间 不 可 测 。 因 此 ， 我 们 等 待 10 秒 钟 再 检 
查 以 确保 派生 完成 。 因 为 这 个 操作 在 浏览 嚣 中 执行， 没 办 法 收 到 通知 ， 所 以 必须 轮 询 
GitHub， 检 查 派生 有 没有 完成 。 在 实际 使 用 时 ， 如 果 发 现 没 有 结束 ， 或 许 要 再 次 检查 ， 
以 防 GitHub 正在 操作 中 。 

使 用 "forking" 键 注册 一 个 消息 ， 我 们 可 以 在 HTML 模板 中 显示 这 个 消息 ， 告 诉 用 户 
正在 复 刻 中 。 这 个 函数 稍 后 定义 ， 它 的 基本 作用 是 存储 这 个 键 和 要 显示 的 字符 串 ， 当 
消息 为 空 时 就 去 掉 通 知 。 

最 后 ， 调 用 annotateAfterForkCompletes 方法 ， 在 整个 过 程 完全 结束 后 向 派生 的 仓库 添 
加 数据 。 












































7 





看 编写 派生 完成 后 向 仓库 添加 评注 的 代码 ; 








$scope.annotateAfterForkCompletes = function() { © 
$scope.forkedRepo = gh.getRepo( $scope.username, "spa.coffeete.ch" ); 
$scope.forkedRepo.read( "gh-pages", "cities.json", function(err, data) { 
if( err ) { 
$timeout( $scope.annotateAfterForkCompletes, 10000 ); 
} 


else { 
$scope.notifyWaiting( "annotating", 
"Annotating data on GitHub" ); @ 
// 把 新 数据 写 入 仓库 
$scope.appendQuirkToShop(); 





var newData = JSON.stringify( $scope.shops, stripHashKey, 2 ); © 
$scope.forkedRepo.write('gh-pages', $scope.city.name + '.json', @ 
newData, 
'Added my quirky information ' ， 
function(err) { 
if( !err ) { 
// 发 起 评注 数据 的 拉 取 请 求 
var pull = {©@ 
title: "Adding quirky information to 
$scope.shopToAnnotate.name, 
body: "Created by :" + $scope.username, 
base: "gh-pages", 
head: $scope.username + 








+ 


+ "gh-pages" 
target = gh.getRepo( "xrd", "spa.coffeete.ch" ); @ 
target.createpullRequest( pull, 

function( err, pullRequest ) {©@ 
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if( !err ) { 
$scope.notifyWaiting( "annotated", 
"Successfully sent annotation request" ); @ 
$timeout( 
function() { 
$scope.notifyWaiting( undefined ) 
}, 5000 ); 
$scope.$apply(); © 


} 
je 
} 
$scope.$apply(); 
} 
} 
$scope.$apply(); 
} ); 


确认 派生 结束 后 ， 我 们 需要 获取 新 派生 的 仓库 。 使 用 用 户 登 录 时 提供 的 用 户 名 构建 仓 
库 对 象 ， 然 后 从 仓库 中 读 取 cities.json 文件 。 如 果 能 成 功 读 取 这 个 文件 (err 对 象 的 值 
不 为 真 )， 就 表明 可 以 开始 编辑 数据 了 。 

通知 UI 我 们 正在 发 表 评注 ， 告 诉 用 户 在 处 理 评 注 请 求 的 过 程 中 要 等 待 。 

JSON.stringify 把 对 咖啡 店 的 评注 对 象 转 换 成 JSON 对 象 。 即 便 你 以 前 用 过 JSON. 
stringtfy， 可 能 也 不 知道 它 还 有 两 个 参数 〈 除 想 序 列 化 的 对 象 之 外 )。 第 二 个 参数 的 
作用 是 序列 化 时 过 滤 对 象 ， 忽 略 指 定 的 元 素 。 第 三 个 参数 的 作用 是 指定 是 否 以 及 如 何 
缩 进 得 到 的 JSON。 我 们 把 第 一 参数 指 定 为 stripHashKey 函数 ， 删 掉 Angular 跟踪 数 
据 的 $$hashKkey， 把 第 三 个 参数 设 为 缩 进 量 。 缩 进 后 拉 取 请 求 更易 阅 读 ， 因 为 JSON. 
stringify 默认 把 对 象 序列 化 成 一 个 长 长 的 JSON 字符 串 不 易于 计算 差异 ， 而 缩 进 后 可 
以 逐 行 计算 差异 。 

然后 ， 使 用 write 函数 把 数据 写 入 派生 的 仓库 中 。 如 果 写 入 成 功 ， 最 后 一 个 参数 ， 也 就 
是 回调 函数 中 的 错误 值 会 是 未 定义 的 。 

如 果 错 误 是 未 定义 的 ， 我 们 可 以 向 源 仓 库 发 起 拉 取 请 求 。 为 此 ， 我 们 要 创建 一 个 拉 取 
请 求 ， 将 其 提供 给 GitHub.js 库 中 发 起 拉 取 请 求 的 方法 。 

获取 拉 取 请 求 目 标 〈 即 源 仓库 ) 的 引用 。 

然后 ， 向 目标 发 起 拉 取 请 求 。 这 个 函数 的 第 一 个 参数 是 前 面 创建 的 拉 取 请 求 对 象 ， 第 
二 个 参数 是 一 个 回调 。 如 果 请 求 失 败 ， 回 调 会 收 到 一 个 错误 代码 ;否则 会 收 到 一 个 拉 
取 请 求 对 象 。 
请 求 成 功 后 ， 我 们 可 以 通知 UI， 告 诉 它 评注 过 程 结束 了 ， 等 5000 毫秒 〈 即 5 秒 ) 后 
把 通知 消息 删 掉 。 

前 面 说 过 ， 只 要 在 第 三 方 库 (如 GitHub.js) 的 回调 中 ， 就 要 使 用 $apply() 通知 
Angular， 告 诉 它 作 用 域 对 象 变 了 。 
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我 们 要 实现 三 个 辅助 方法 : 





$scope.appendQuirkToShop = function() { @ 
if( undefined == $scope.shopToAnnotate.information ) { 
$scope.shopToAnnotate.information = []; 
站 


$scope.shopToAnnotate.information.push( $scope.annotation ); 


}; 


function stripHashKey( key, value ) { 名 
if( key == "$$hashKey" ) { 
return undefined; 
} 


return value; 


} 


$scope.notifyWaiting = function( state, msg ) {©® 
if( state ) { 
$scope.waiting = {}; 
$scope.waiting.state = state; 
$scope.waiting.msg = msg; 


} 
else { 

$scope.waiting = undefined; 
} 


@ 在 appendQuirkToshop 函数 中 ， 我 们 判断 评注 数组 有 没有 定义 ;如 果 没 有 定义 ， 那 么 创 
建 一 个 空 数 组 ， 然 后 把 评 广 添 加 到 里 面 。 这 么 做 是 为 了 保证 向 未 定义 的 数组 中 添加 对 
象 时 应 用 不 会 崩溃 。 

@ 定义 在 JSON.stringify 函数 中 使 用 的 转换 函数 。 使 用 ng-repeat 指令 时 ，AngularJS 会 
向 对 象 中 添加 一 个 跟踪 属性 ($$hashKey)， 这 个 函数 的 作用 是 把 它 从 拉 取 请 求 数据 中 过 
滤 掉 。 

@ notifywaiting 的 作用 (显然 ) 是 通知 用 户 。 创 建 一 个 waiting 对 象 ， 然 后 更 新 状态 
(应 用 通过 这 个 状态 判断 要 不 要 显示 消息 )， 并 指定 一 个 消息 。 如 果 提 供 空 消息 ， 那 就 
意味 着 销毁 对 象 ， 也 就 是 从 UI 中 删除 消息 。 


























接 下 来 要 修改 HTML， 把 状态 消息 开放 给 UI 使 用 。 
<input class="ctinput" ng-model="search" 
placeholder="Enter search parameters..."/> 
<h3 ng-show="city">Current city: {{city.name}}</h3> 


<div ng-show="waiting"> 
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{{waiting.msg}} 
</div> 


9.7 ”接受 拉 取 请 求 





有 人 为 咖啡 店 添加 评注 后 ， 源 仓库 的 属 主 会 收 到 GitHub 发 送 的 拉 取 请 求 通知 ( 见 








图 9-5)。 





xrd / spa.coffeete.ch 





对 Conversation 0 CCcommits i 国 Files Changed 所 


BurningOnUp commented 6 minutes ago 


Created by :BurningOnUp 


器 Added my quirky information 


This pull request can be automatically merged. 
You can also merge branches on the command line. 


write Preview 








& Unwatch ~ 


Adding quirky information to Very Good Coffee Shop #1 


BumingOnUp wants to merge 1 commit into xrd:gh-pages from Burning0nUp:gh-pages 


= Ez 


Comments are parsed with GitHub Flavored Markdown 


hl 


去 Siar 0 


VB Forl 





4 国 加 加 加 


Labels 


None yet 


Milestone 


No milestone 


Assignee 


No one assigned 


Notifications 


qd* Unsubscribe 





9-5: 通过 拉 取 请 求 添加 信息 


我 们 可 以 通过 GitHub 集成 的 在 线 差异 工具 审查 改动 ( 见 图 9-6)。 





Added my quirky information 
了 gh-pages 


对 BumingOnUp authored just now 1 parent 7d7d259 


习 Showing 1 changed file with 4 additions and 1 deletion 


5 回回 加 回国 portLand . json 


EE 
素 


ee -12,7 +12,10 ee 

{ 
"name": "Very Bad Coffee Shop"， 
"latitude": 45.522181, 
"longitude": -122.63709 
"longitude": -122.63709, 
"information": [ 

"No turtles allowed" 

] 

}， 

{ 


"name" : 


++++ 1 


"Mediocre coffee Shop", 





Browse code 


commit 1b42d18ffec92b4312901159476d163d3c828e09 


Show Diff Stats 


View 





9-6: 在 GitHub 中 审查 评注 拉 取 请 求 的 差异 
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我 们 可 以 清楚 地 看 到 贡献 者 所 做 的 改动 : 用户 添加 了 一 条 评注 ， 说 “禁止 携带 乌龟 ”。 既 
然 这 样 ， 那 么 下 次 与 Morla 约会 时 可 能 要 考虑 换个 地 方 了 。 差 异 中 以 绿色 显示 的 信息 能 吸 
引 阅 读者 的 目光 ， 只 要 不 把 JSON.stringify 的 第 三 个 参数 设 为 未 定义 ， 就 能 获得 这 个 效 
果 。 可 惜 ， 第 一 行 的 差异 只 是 多 个 辟 号 ， 不 过 整体 依然 十 分 便于 阅读 。 


9.8 ”实现 安全 的 登录 方式 


如 有 果 我 在 网 上 遇 到 这 个 应 用 ， 那 我 绝对 不 会 使 用 它 提 交 数 据 ， 因 为 它 要 我 输入 GitHub 的 
用 户 名 和 密码 。 这 么 做 是 想 让 我 信任 应 用 的 作者 。 我 所 说 的 “信任 ”是 指 确信 应 用 的 作者 
` 会 恶意 使 用 我 的 凭据 做 不 法 的 事 ， 还 要 确信 应 用 的 作者 没有 埋 下 漏洞 ， 不 会 让 攻击 者 入 
侵 身 份 验证 过 程 ， 把 我 的 凭据 偷 走 。 我 的 很 多 在 线 服 务 都 使 用 GitHub 作为 身份 验证 方式 ， 
因此 我 绝 不 会 轻易 把 凭据 提供 给 一 个 Web 应 用 。 


幸好 ， 询 问 密码 还 有 其 他 方式 : OAuth。 
































使 用 OAuth 的 话 ， 用 户 直接 在 GitHub 中 输入 凭据 。 如 果 用 户 开启 了 双重 身份 验证 ， 
GitHub 依然 能 验证 用 户 的 身份 (不 过 我 们 这 个 简单 的 实现 无 法 处 理 这 种 身份 验证 过 程 )。 
输入 凭据 后 ，GitHub 会 判断 我 们 是 不 是 声称 的 那个 人 ， 然 后 返回 应 用 ， 赋 予 请 求 的 权限 。 








使 用 OAuth 有 很 多 好 处 。GitHub 会 为 应 用 提供 OAuth 令 牌 ， 令 牌 中 封装 着 
有 权 在 GitHub 中 执行 的 操作 、 是 不 是 只 读 权 限 ， 以 及 能 不 能 读 写 数据 。 因 
此 ， 请 求 权 限 的 服务 可 以 只 要 求 修 改 GitHub 中 的 部 分 数据 。 这 样 用 户 会 更 
相信 应 用 ， 因 为 他 们 知道 应 用 不 能 触 碰 他 们 在 GitHub 中 保存 的 私有 数据 。 
比如 说 ,我们 可 以 只 请 求 访问 Gist 的 权限 ， 而 不 请 求 访问 仓库 的 权限 。 而 且 
OAuth 令 牌 有 一 大 优点 : 可 以 吊销 。 因 此 ， 当 执行 特定 的 操作 时 ， 我 们 可 以 
销毁 令 牌 ， 撤 销 访 问 权 限 。 如 果 使 用 用 户 名 和 密码 ， 只 有 更 换 密码 才能 撤销 
访问 权限 ， 这 意味 着 所 有 使 用 那个 密码 的 地 方 (密码 管理 工具 ， 以 及 使 用 用 
户 名 和 密码 登录 的 其 他 应 用 ) 都 要 修改 。 使 用 OAuth 时 ， 随 时 可 以 吊销 令 牌 
(在 GitHub 中 操作 很 简单 )， 而 且 其 他 服务 不 会 受到 影响 。 
















































































下 面 我 们 来 修改 应 用 ， 使 用 OAuth。 











9.8.1 身份 验证 需要 服务 器 

截至 目前 ， 我 们 把 所 有 文件 都 发 布 到 GitHub 中 了 ， 也 就 是 都 交 给 GitHub 托管 了 。 可 惜 
的 是 ， 身 份 验证 组 件 不 能 托管 在 GitHub 中 ， 因 为 我 们 要 通过 GitHub 以 安全 的 方式 验证 
用 户 的 身份 ， 获 取 OAuth 令 牌 。 目 前 ， 没 有 完美 的 客户 端 方案 (只 能 使 用 运行 在 浏览 器 
中 的 静态 HTML 和 JavaScript) 能 做 到 这 一 点 。 其 他 身份 验证 提供 商 ， 例 如 Facebook， 在 
SDK 中 提供 了 纯 JavaScript 登录 功能 ， 但 是 GitHub 基于 安全 考虑 ， 尚 未 发 布 纯 客 户 端 身 
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份 验证 方案 。 


因此 ， 为 了 验证 身份 ， 我 们 要 使 用 服务 器 。 最 简单 的 做 法 是 运行 一 个 小 型 身份 验证 服务 
器 ， 把 身份 验证 过 程 交 给 它 处 理 ， 处 理 完 毕 后 ， 再 返回 GitHub 中 托管 的 应 用 。 我 在 本 章 
对 应 的 仓库 中 提供 了 相关 代码 (使 用 服务 器 端 JavaScript， 即 NodeJS 编写 ) 。 可 是 ， 即 便 
是 简单 的 身份 验证 系统 ， 这 么 做 也 有 点 小 题 大 做 。 如 果 能 把 身份 认证 过 程 交 给 第 三 方 处 
里 ， 系 统 的 代码 量 和 复杂 程度 都 将 大 大 减少 。 


















































YH 





9.8.2 ”使 用 Firebase 处 理 身份 验证 过 程 

我 们 不 会 自己 搭建 服务 器 ， 让 它 与 GitHub API 通信 以 及 验证 身份 ， 而 是 把 这 个 过 程 交 给 
Firebase 来 做 。Firebase 是 实时 通信 工具 ， 能 很 好 地 与 我 们 选择 的 AngularJS 集成 。 目 前 
最 简单 也 是 最 安全 的 方案 是 ， 使 用 Firebase 提供 的 AngularJS 绑 定 “AngularFire”)， 以 及 
集成 好 的 GitHub 身份 验证 组 件 (“Simple Login”)。 这 两 个 库 能 为 我 们 解决 身份 验证 问题 ， 
而 且 所 有 代码 还 都 托管 在 GitHub 中 。 把 身份 验证 过 程 交 给 Firebase 处 理 很 简单 ， 我 们 只 需 
修改 托管 在 GitHub 中 的 应 用 ， 把 凭据 和 GitHub OAuth 作用 域 提供 给 Firepase， 这 样 用 户 
管理 功能 就 交 给 Firebase 去 做 了 。 












































首先 创建 一 个 新 GitHub 应 用 。 在 GitHub.com 的 右上 角 点 击 “Settings” 链 接 ， 在 打开 的 页 
看 中 点 击 靠近 底部 的 “OAuth applications” 链 接 。 在 右 栏 中 点 击 “Developer applications” 
标签 页 ， 然 后 点 击 “Register a new application” 按 钮 。“Authorization callback URL” 中 要 
填写 https://auth.firebase.com/auth/github/callback。 然 后 ， 点 击 “Register application ”按钮 ， 
保存 应 用 ， 如 图 9-7 所 示 。 
































接 下 来 ， 注册 一 个 Firebase 账户 。 然 后 ， 在 Firebase 中 新 建 一 个 应 用 ,命名 为 “CoffeeTech”。 
应 用 的 URL 必须 独一无二 ， 你 可 以 使 用 “coffeetech-<USERNAME>”， 记 得 把 USERNAME 
换 成 你 的 GitHub 用 户 名 。 创 建 应 用 后 ， 点 击 “View Firebase” 按 钮 。 此 时 你 会 看 到 设置 界 
看 ， 点 击 “Simple Login”， 然 后 点 击 “GitHub”， 如 图 9-8 所 示 。 
































注 1: 其 中 链接 文本 和 按钮 文本 已 根据 GitHub 的 新 版 UI 做 了 更 新 。 一 一 译 者 注 
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Authorized applications Developer applications 


Register a new OAuth application 


Application name 


CoffeeTech GitHub Authentication Provider 


Something users will recognize and trust 


cp 


Drag & drop 


Homepage URL 


http://spa.coffeete.ch 


The full URL to your application homepage 


or choose an image 


Application description 


Application description is optional 


This is displayed to all potential users of your application 


Authorization callback URL 





| https://auth.firebase.com/auth/github/callback 





Your application's callback URL. Read our OAuth documentation for more information 











9-7: 为 了 使 用 OAuth， 新 建 一 个 GitHub 应 用 








号 Firebase viewiNG coFFEETECH 





Authorized Request Origins 


OAuth requests to Firebase Simple Login are only permitted from domains you specify. This a 
authentication only. Learn more » 


localhost || 127.0.0.1 
Login Session Length 


Customize the amount of time your users are authenticated with Simple Login. 


he 24 hours 





Authentication Providers 


Facebook Twitter GitHub Persona Email & Password Anonymous 


Enable authentication with GitHub in your application. Leam more » 


DD Enabled 
GitHub Client ID: 1234567890abcdefghijk 
GitHub Client Secret: [ 0987654321kmnopqrstuv 











9-8: 把 登录 过 程 交 给 Firebase 处 理 
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最 后 ， 复 制 GitHub 客户 端 ID 和 密令 ， 粘 贴 到 Firebase Simple Login 界面 中 设置 GitHub 提 
供 商 的 部 分 。 记 得 勾 选 “Enabled”， 启 用 这 个 提供 商 。 


























至 此 ， 我 们 在 GitHub 中 创建 了 一 个 登录 应 用 ， 做 了 相关 配置 ， 让 它 使 用 Firebase 服务 ， 还 
配置 了 Firebase， 让 它 使 用 那个 GitHub 应 用 。 我 们 希望 所 有 功能 ， 尤 其 是 外 部 服务 ， 都 被 
测试 履 盖 。 那 么 ， 接 下 来 编写 覆盖 这 个 功能 的 测试 。 





9.8.3 测试 Firebase 


由 于 我 们 从 CDN 中 加 载 Firebase， 首 先 要 使 用 简单 的 shim 来 模拟 Firebase 构造 方法 。 把 
下 述 代 码 写 入 firebase-mock.js 文件 : 





var Firebase = function (url) { 


} 


anguLar.moduLe( 'firebase', [] ); 


为 了 测试 代码 ， 我 们 要 对 coffeetech-annotate.spec.js 文件 做 下 述 改 动 : 
beforeEach( module( "coffeetech" ) ); 


var mockFirebase = mockSimpleLogin = undefined; 
function generateMockFirebaseSupport() { © 
mockFirebase = function() {}; 
mockSimpleLogin = function() { 
return { 
'$login': function() { 
return { then: function( cb ) { 
cb( { name: "someUser", 
accessToken: "abcdefghi" } ); 


3 


} 
和 
} 


var $timeout; 
beforeEach( inject( function ($controller, $rootScope, $injector ) { 
generateMockRepositorySupport(); 
generateMockPrompt(); 
generateMockFirebaseSupport(); @ 
$timeout = Sinjector .get( '$timeout' ); 
scope = $rootScope. $new(); 
ctrl = $controller( "GithubCtrl", 
{ $scope: scope, 
Github: ghs, 
'$timeout': $timeout, 
'$Swindow': prompter, 
'$firebase': mockFirebase, 
'$SfirebaseSimpleLogin': mockSimpLeLogin } ); © 
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@ 
© 


下 六 


describe( "#annotate", function() { 
it( "should annotate a shop", function() { 
scope.auth = mockSimpleLogin( mockFirebase() ); @ 
scope.city = PORTLAND 
var shop = { name: "A coffeeshop" } 
scope.annotate( shop ); 
expect( prompter .prompt.caLLs.Length ).toEqual( 1 ); © 
expect( scope.shopToAnnotate ).toBeTruthy(); 
expect( scope.username ).not.toBeFalsy(); 
expect( scope.annotation ).not.toBeFalsy(); 


expect( repo.fork ).toHaveBeenCalled(); 
expect( scope.waiting.state ).toEqual( "forking" ); 
$timeout.flush(); 


expect( scope.forkedRepo ).toBeTruthy(); 

expect( repo.read ).toHaveBeenCalled(); 

expect( repo.write ).toHaveBeenCalled(); 

expect( repo.createPuLLRequest ).toHaveBeenCalled(); 
expect( scope.waiting.state ).toEqual( "annotated" ); 
$timeout.flush(); 


expect( scope.waiting ).toBeFalsy(); 


添加 generateMockFirebaseSupport() 函数 ， 用 于 创建 模拟 的 Firebase 对 象 和 简 


对 象 。 
调用 这 个 函数 ， 创 建 驶 件 。 





在 测试 中 ， 我 们 使 用 $controtler 实例 化 方法 注入 这 些 双 件 ， 而 不 让 AngularJS 注入 真 


正 的 对 象 。 现 在 ， 需 要 向 控制 器 注入 对 象 的 测试 都 要 这 样 修改 。 
修改 #annotate 测试 ， 创 建 auth 对 象 (通常 在 初始 化 时 创建 )。 
只 需 为 评注 数据 提示 一 次 (不 再 需要 提示 输入 用 户 名 和 密码 了 )。 





9.8.4 ”实现 Firebase 登 录 功 能 


现在 ， 为 我 们 的 AngularJS 应 用 添加 Firebase 支持 。 在 加 载 AngularJS 的 元 素 后 面 引 入 
Firebase 的 支持 库 。 





<script src="angular.js"></script> 
<script src='https://cdn.firebase.com/vO/firebase.js'></script> 
<script 


src='https://cdn.firebase.com/libs/angularfire/0.6.0/angularfire.min.js'> 


</script> 
<script 


自 








src='https://cdn.firebase.com/js/simple-login/1.2.5/firebase-simple-login.js'> 


</script> 
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我 们 要 对 coffeetech.js 文 伯 








做 几 处 改动 。 首 先 ， 把 Firebase 导入 AngularJS 模块 。 此 外 ， 之 
前 要 把 用 户 名 和 密码 作为 参数 传 给 GitHub 服务 ， 但 是 现在 我 们 要 使 用 稍微 不 同 的 方法 签 
名 ， 传 人 OAuth 令 牌 。 














var mod = angular.module( 'coffeetech', [ 'firebase' ] ); 


mod.factory( 'Github', function() { 
return { 
create: function(token) { 
return new Github( { token: token, auth: 'oauth' } ); 
} 


}; 
由) 


实例 化 控制 器 时 ， 要 注入 Firebase 和 FirebasesimpleLogin， 然 后 在 init 方法 中 初始 化 。 
mod.controller( 'GithubCtrl', [ '$scope', 'Github', 'Geo', '$window', '$timeout', 
'$Sfirebase', '$firebaseSimpleLogin’', 
function( $scope, ghs, Geo, S$Swindow, $timeout, 
sfirebase, $firebaseSimpleLogin ) { 


$scope.init = function() { 


var ref = new Firebase( 'https://coffeetech.firebaseio.com' ); 
$scope.auth = $firebaseSimpleLogin( ref ); 


$scope.getCurrentLocation( function( position ) { 
$scope.latitude = position.coords.latitude; 





然后 ， 发 表 评 注 时 ， 要 提供 Firebase 返回 的 auth 令 牌 。 除 此 之 外 ， 还 要 对 流程 做 些小 
改动 。 


$scope.annotate = function( shop ) { 
$scope.shopToAnnotate = shop; 


$scope.auth.$login( 'github', { scope: 'repo' } ).then( 
function( user ) {©@ 


$scope.me = User; 
$scope.username = user .name; 


$scope.annotation = S$window.prompt( "Enter data to add" ); @ 


if( $scope.annotation ) { 
gh = ghs.create( $scope.me.accessToken ); © 
toFork = gh.getRepo( "xrd", "spa.coffeete.ch" ); 
toFork.fork( function( err ) { 








@ 在 Firebase SimpleLogin 服务 创建 的 auth 对 象 上 调用 $logiin 方法 。 这 个 方法 返回 一 个 


promise 对 象 ， 这 个 接口 有 个 then() 方法 ， 在 登录 成 功 时 调用 。then( ) 方法 调用 指定 的 
回调 函数 ， 提 供用 户 对 象 。 
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@ 我 们 还 要 提示 用 户 输入 一 个 信息 一 一 评注 数据 。 这 个 信息 可 以 使 用 其 他 方式 获取 ， 例 
如 使 用 HTMLS5 模式 对 话 框 ， 不 过 现在 这 么 做 已 经 能 达到 目的 。 毕 竟 ， 现在 只 提示 一 
次 ， 而 不 用 提示 三 次 。 

@ 准备 好 派生 时 ， 要 使 用 令 牌 创建 用 户 对 象 。 














改 好 之 后 ， 可 以 点 击 “Add factoid” 按 钮 ， 此 时 会 打开 如 图 9-9 所 示 的 界面 ， 这 表明 我 们 
将 使 用 GitHub 登录 (通过 Firebase SimpleLogin 服务 ) 。 





Authorize application 到 
spa.coffeete.ch local auth by @xrd would like permission 机 tPF 


to access your account 


Review permissions 
spa.coffeete.ch local auth 


吕 Personal user data 
Email addresses (read-only) B® No description 


Visit application's website 


Repositories 


Public and private 大 
© Learn more about OAuth 














图 9-9:, 使 用 Firebase 通过 GitHub 登录 的 最 后 一 步 

验证 身份 之 后 的 执行 流程 与 之 前 (使 用 用 户 名 和 密码 ) 一 样 。 我 们 可 以 优化 一 下 ， 在 调用 
$login() 方法 之 前 检查 用 户 是 否 已 经 登录 ， 不 过 这 里 先 不 这 么 做 ， 也 就 是 说 每 次 点 击 那 个 
按钮 都 会 立刻 跳出 登录 界面 。 

















用 户 登 录 后 ， 会 重 定向 到 应 用 ， 我 们 可 以 通知 他 们 ， 告 诉 他 们 所 做 的 贡献 已 通过 拉 取 请 求 
提交 了 。 用 户 的 贡献 与 他 们 的 GitHub 账号 是 关联 的 ， 拉 取 请 求 被 接受 后 会 收 到 标准 的 通 
知 ， 因 此 此 处 不 用 再 实现 通知 功能 。 





9.9 小 结 


本 章 使 用 JavaScript 构建 了 一 个 不 用 服务 器 的 应 用 ， 这 个 应 用 为 用 户 提供 可 搜索 的 咖啡 店 
数据 库 ， 而 且 可 以 使 用 Pull Request API 以 安全 的 方式 接受 贡献 。 我 们 可 以 完全 忽略 数据 
系统 的 管理 功能 ， 而 将 其 交 给 GitHub 处 理 。 我 们 的 单 页 应 用 只 关 广 一 件 事 : 开发 强大 且 
实用 的 应 用 。 
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附录 A 
GitHub 企 业 版 





大 多 数 人 把 GitHub (公司 ) 与 GitHub.com (网 站 ) 划 等 号 ， 但 是 二 者 并 非 同一 个 事物 。 


现在 ， 开 源 和 闭 源 软件 都 喜欢 托管 在 GitHub 网 站 中 ， 但 这 不 是 GitHub 公司 的 唯一 产品 。 
除 此 之 外 ，GitHub 公司 的 另 一 个 主力 产品 是 GitHub 企业 版 。 这 个 版 本 可 以 部 署 到 企业 的 
防火 墙 之 后 ， 相 当 于 企业 专用 的 GitHub.com。 














在 用 户 看 来 ， 这 两 个 产品 非常 相似 ， 其实， 二 者 之 间 有 明显 的 差别 。 有 时 很 难 想象 企业 版 
能 解决 什么 困境 ， 但 是 要 知道 ， 它 是 针对 大 型 团队 的 。 





rm 
A.1 二 
使 用 GitHub 企业 版 可 不 是 注册 一 个 账户 那么 简单 ， 我 们 自己 要 负责 全 部 基础 设施 和 维护 
工作 ， 包 括 安装 、 升 级 、 系 统 维护 、 让 设备 始终 运行 ， 等 等 。 不 过 ， 如 果 你 的 公司 决定 使 
用 企业 版 ， 说 明 公 司 已 经 雇用 了 熟知 这 些 操 作 的 专业 人 士 。 




















GitHub 团队 努力 做 得 更 好 ， 让 维护 人 员 更 轻松 。 企 业 版 自 带 不 同 格式 的 虚拟 机 ， 很 可 能 
一 种 符合 贵 公 司 基础 设施 的 要 求 。 虚 拟 机 运行 起 来 之 后 ， 大 多 数 配 置 都 可 以 在 Web 界面 中 
设置 ， 不 过 有 些 棘手 的 配置 ， 如 网 络 配置 和 端口 转发 ， 外 行 很 难 做 到 正确 设置 。 

















A.2 管理 


企业 版 的 运行 环境 由 我 们 自己 负责 ， 这 可 不 像 GitHub.com 用 户 那 么 轻松 ， 我 们 要 关注 很 
多 问题 。GitHub 企业 版 提供 了 管理 界面 ， 用 于 处 理 这 些 问 题 。 这 个 界面 是 GitHub.com 没 
有 的 ， 在 这 里 可 以 做 很 多 事情 ， 例 如 管理 系统 资源 、 报 告 、 搜 索 ， 等 等 。 


此 外 ，GitHub.com 有 自己 的 一 套用 户 系统 ， 而 企业 版 能 与 公司 现 有 的 身份 认证 系统 集成 。 
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这 样 ， 公 司 的 开 部 门 可 以 在 一 处 管理 所 有 用 户 身份 ， 雇 用 新 员工 时 无 需 在 多 处 创建 账户 。 
一 开始 切换 系统 时 可 能 要 为 儿 千 个 人 创建 新 账号 ， 不 过 既然 能 集成 现 有 系统 ， 整 个 过 程 就 
会 变 得 简单 。GitHub 企业 版 支持 多 种 身份 验证 系统 ， 包 括 LDAP、SAML， 以 及 传统 的 电 
子 邮件 和 密码 。 























A.3 ”端点 


GitHub API 在 企业 版 中 都 可 以 使 用 ， 只 不 过 请 求 的 地 址 不 是 https://api.github.com/， 而 是 
https:/<hostname>/apiv3。 可 以 想象 ， 有 些 用 户 同时 拥有 企业 版 和 GitHub.com 账户 ， 而 且 
很 多 应 用 都 开始 支持 这 种 情况 。 


A.4 单独 的 主机 名 与 挂 载 点 


GitHub.com 与 企业 版 的 主要 区 别 通常 是 主机 名 不 同 。GitHub.com 为 不 同 的 内 容 提 供 了 不 
同 的 主机 名 ， 下 面 是 不 完整 的 列表 。 

















。 github.io 
存 贮 用 户 和 项 目的 Jekyll 博客 


。 gist.github.com 
存 贮 : Gist 


。 raw.githubusercontent.com 


存 贮 原始 页 面 (未 经 处 理 的 文件 ) 

















基于 多 方面 的 原因 ，GitHub 企业 版 没有 提供 这 样 的 映射 关系 。 企 业 版 安装 可 能 是 下 面 这 
样 的 。 


























。 github.bigdevcorp.example.com/pages/xrd/somerepo 


存 贮 gh-pages 网 站 


。 github.bigdevcorp.example.com/gists 
存 贮 Gist 











可 以 看 出 ， 企 业 版 通常 把 子 域名 映射 到 子 目 录 上 ， 而 不 是 单独 的 主机 名 。 这 样 简化 了 企业 
版 的 安装 。 不 过 ， 这 意味 着 有 些 工 具 要 重新 配置 。 





对 命令 行 工 具 Gist (https://github.com/defunkt/gist) 来 说 ， 我 们 要 导出 一 个 环境 变量 ， 指 定 
Gist 的 URL: 


$ export GITHUB_URL=http://github.bigdevcorp.example.com/ 
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对 命令 行 工具 Hub (https://github.com/github/hub) 来 说 ， 我 们 要 导出 另 一 个 环境 变量 
GITHUB_HOST: 


$ GITHUB_HOST=github.bigdevcorp.example.com hub clone myproject 


A.5 命令 行 客户 端 工 具 : cURL 


第 1 章 说 明了 如 何 使 用 cURL 向 GitHub.com 网 站 的 API 发 送 请 求 。 如 果 想 使 用 cURL 请 
求 企 业 版 网 站 ,方式 有 点 不 同 : 





$ curl -i https://github.bigdevcorp.example.com/api/v3/search/repositories?q=@ben 


A.6 ”使 用 客户 端 库 的 请 求 示例 


大 多 数 客户 端 库 都 支持 配置 使 用 不 同 的 端点 ， 而 使 用 GitHub 企业 版 时 必须 这 么 做 。 








本 书 演示 如 何 使 用 5 门 语言 连接 GitHub: Ruby、Java、JavaScript、Python 和 C#。 下 面 
是 各 门 语言 的 示例 。 参 照 这 些 代 码 片段 ， 你 可 以 对 书 中 的 任何 示例 进行 改造 ， 让 它 适应 
GitHub 企业 版 。 











A.6.1 Ruby 
对 Ruby 客户 端 Octokit 来 说 ， 要 使 用 类 似 下 面 的 代码 : 














github = Github.new 

basic_ auth: 'login:password', 

endpoint: 'https://github.bigdevcorp.example.com/api/v3/" 
puts github.repos. list 


A.6.2 Java 
对 Java 库 EGit 来 说 ， 要 使 用 下 述 方式 指定 企业 版 端点 : 
GitHubClient client = new GitHubClient("github.bigcorpdev.example.com"); 


UserService us = new UserService(client); 
us.getUser("internaluser"); 


创建 某 种 以 GitHub 支持 的 服务 对 象 时 ， 要 把 客户 端 对 象 传 给 服务 的 构造 方法 。 


此 外 要 注意 ， 这 个 库 专 门 针 对 GitHub API 的 第 三 版 (v3)。 如 果 想 使 用 新 版 API， 要 使 用 
正确 的 EGit 版 本 。 如 果 你 的 企业 版 由 于 某 种 原因 无 法 升级 ， 那 就 不 能 使 用 这 个 Java 客户 
端 访问 旧版 API。 
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A.6.3 JavaScript 
本 书 使 用 的 JavaScript 库 (GitHub.js) 通过 下 述 句 法 指定 GitHub 企业 版 后 端 : 


var github = new Github({ 
apiUrL: "https://github.bigdevcorp.example.com/api/v3" 


DD); 


A.6.4 Python 


第 4 章 使 用 的 agithub 客户 端 不 能 指定 使 用 企业 版 端点 创建 GitHub 客户 端 。 如 果 想 使 用 企 
业 版 端点 ， 要 定义 一 个 继承 自 内 置 agithub.Github 类 的 新 类 ， 然 后 使 用 这 个 类 创建 客户 端 。 


cLass GitHubEnterprise(agithub.API): 
def _init (self, api_url, *args, **kwargs): 
props = Connectionproperties( 

api_url = api_url, 

secure_http = True, 

extra_headers = { 
'accept' : "application/vnd.github.v3+json' 
} 

) 


self.setClient(Client(*args, **kwargs)) 
seLf .setConnectionProperties(props) 


g = GitHubEnterprise('github.mycorp.com', 'myusername', 'mypassword') 


A.6.5 C# 


Octokit 库 默 认 连 接 GitHub.com， 不 过 也 能 轻易 让 它 使 用 其 他 API 地 址 。 把 实例 化 
GitHubClient 对 象 的 代码 换 成 下 面 这 样 就 行 。 














var ghe = new Uri("https://github.myenterprise.com/"); 
var client = new GitHubClient(new ProductHeaderValue("my-cool-app"), ghe); 


A.7 管理 API 


企业 版 有 个 专 有 的 API 端点 ， 这 是 GitHub.com 不 具备 的 ， 叫 作 Management Console API。 
这 个 API 用 于 检查 设置 、 维 护 SSH 密 钥 、 管 理 许 可 证 ， 等 等 。 可 以 在 Web 界面 中 执行 的 
管理 操作 ， 几 乎 都 能 通过 这 个 API 操作 (因此 可 以 根据 需求 编写 管理 脚本 )。 


A.8 文档 


企业 版 API 的 文档 在 这 里 : https://developer.github.com/v3/enterprise。 
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附录 B 
GitHub 对 Ruby、NodeJS (和 shell) 


的 利用 





GitHub 的 几 位 创始 人 深 爱 Ruby 编程 语言 ， 为 Ruby 做 了 一 些 贡献 ， 因 此 本 书 涉及 Ruby 的 
内 容 很 多 。 

最 近 几 年 ，NodeJS (服务 器 端 JavaScript) 越 来 越 流行 ， 使 得 JavaScript 变 成 一 门 十 分 吸引 
人 的 语言 ， 因 为 它 在 客户 端 和 服务 器 端 都 能 使 用 。GitHub 开发 了 几 个 使 用 NodeJS 编写 的 
开源 项 目 ， 十 分 受 欢迎 。 








鉴于 此 ， 这 篇 附录 再 进一步 说 明 如 何 使 用 这 两 门 语言 。 


此 外 ， 熟 练 使 用 shell 也 有 好 处 。 有 了 GUI 程序 之 后 ， 我 们 很 少 使 用 命令 行 ， 但 是 若 想 
充分 使 用 GitHub API， 一 定 要 在 shell 中 使 用 命令 行 。 下 面 这 些 示例 都 能 在 bash (Bourne 
Again Shell) 中 使 用 ， 而 且 没 有 使 用 bash 的 高 级 功能 (这样 ， 如 果 钟 爱 其 他 shell， 就 能 轻 
易 转 换 ) 。 








B.1 GitHub 和 Ruby 


讲 起 GitHub 的 历史 ,一 定 不 能 跳 过 Ruby 语言 。 在 最 初 操作 Git 的 库 中 ， 使 用 Ruby 编写 
的 Grit 由 Tom Preston Warner (GitHub 三 个 创始 人 之 一 ) 开发 。 你 可 以 把 博客 免费 托管 在 
GitHub 中 ， 而 这 背后 使 用 的 工具 Jekyll 就 是 使 用 Ruby 构建 的 。Gollum， 即 GitHub 维基 采 
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用 的 工具 ， 是 使 用 Ruby 库 Grit 构建 的 。 


若 想 了 解 GitHub， 最 好 懂 一 些 Ruby。 你 无 需 知 道 Ruby 句法 ， 安 装 Ruby 后 就 能 使 用 
GitHub 用 到 的 很 多 工具 。 本 书 不 要 求 你 变 身 Ruby 专家 ， 但 是 你 要 能 读 懂 Ruby 代码 。 本 
书 行文 浅显 易 懂 ， 只 要 具有 基本 的 软件 开发 技能 ， 而 且 精 通 英语 ， 都 能 理解 我 们 使 用 的 工 
具 。Ruby 不 是 完美 的 语言 ， 然 而 却 是 开发 者 工具 包 中 的 一 个 有 用 工具 ， 因 为 Ruby 专注 于 
提高 开发 者 的 效率 。 














B.1.1 安装 Ruby 

安装 Ruby 的 方法 有 很 多 种 ， 但 是 各 有 优 缺 点 。 作 为 长 期 用 户 ， 我 知道 使 用 预 装 的 或 包 管 
理 器 中 的 Ruby 有 多 么 痛苦 。 一 般 而 言 ， 这 样 安装 不 是 最 好 的 方法 。 如 果 你 不 熟悉 Ruby， 
可 以 参照 本 附录 安装 ， 这 里 说 明 的 方法 最 简便 。 




















你 的 系统 中 可 能 已 经 安装 了 某 个 版 本 的 Ruby。Mac OS X 预 装 了 Ruby， 多 个 Linux 发 行 
版 也 是 如 此 (此 外 ， 可 以 使 用 自 带 的 包 管 理 器 安装 ， 快速 又 简单 ， 如 aptrget) 。 不 过 ， 我 
建议 你 使 用 这 里 说 明 的 方法 安装 ， 别 使 用 系统 预 装 的 Ruby。Ruby 包 通 常 要 求 使 用 特定 的 
Ruby 版 本 ， 不 过 可 能 也 支持 其 他 版 本 ， 但 是 可 能 会 遇 到 之 前 没 见 过 的 小 缺陷 。 使 用 这 里 
说 明 的 方法 可 以 轻易 安装 任何 一 版 Ruby， 而 且 可 以 多 个 版 本 共存 。 使 用 这 里 说 明 的 方法 
安装 Ruby 能 确保 使 用 正确 的 版 本 ， 而 且 不 会 干扰 系统 中 预 装 的 Ruby。 
































我 们 使 用 RVM 安装 Ruby。RVM 是 Ruby Version Manager 的 简称 ， 使 用 它 可 以 在 设备 中 
安装 多 个 Ruby 版 本 ， 而 且 相 互 不 冲突 。 为 了 使 用 书 中 的 示例 ， 你 或 许 只 需 安装 一 个 Ruby 
版 本 。 使 用 RVM 可 以 轻易 安装 另 一 个 Ruby 版 本 ， 而 且 不 用 重新 配置 应 用 ， 让 它 使 用 那 
个 版 本 。 


在 不 同 的 操作 系统 中 使 用 RVM 安装 Ruby 的 方法 有 所 不 同 。 如 果 你 使 用 Mac OS X 或 
Linux， 只 需 在 shell 中 执行 下 述 命令 : 














$ \curl -sSL https://get.rvm.io | bash -s stable 
这 个 命令 会 安装 RVM 和 Ruby。 


如 果 使 用 的 是 Windows， 也 可 以 使 用 RVM 安装 Ruby， 不 过 过 程 稍微 复杂 一 些 。 详 情 参 
阅 文档 。 在 Windows 中 更 好 的 安装 方法 是 使 用 虚拟 机 ， 如 VirtualBox (虚拟 机 管理 工具 )， 
把 RVM 安装 到 Linux 虚拟 机 中 。Ruby 和 RVM 对 Windows 的 支持 并 不 好 ， 因 此 通常 最 好 
在 Linux 等 宿主 系统 中 安装 RVM，Ruby 对 这 类 系统 的 社区 支持 更 好 。VirtualBox 和 Linux 
都 是 免费 的 ， 无 需 付费 就 能 使 用 〈 不 过 要 花费 时 间 )。 很 多 带 原 生 扩 展 的 Ruby gem 不 能 在 
Windows 中 编译 ， 所 以 不 用 浪费 时 间 考 虑 了 ， 在 Windows 中 应 该 直接 使 用 完全 免费 的 工 
具 ， 如 VirtualBox 和 虚拟 机 ， 不 要 苦 苦 寻找 解决 方案 了 。 
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B 
下 


B 


.1.2 重要 的 Ruby 和 RVM 概 念 


相 是 使 用 Ruby 和 RVM 时 的 几 个 小 提示 。 














Gemfile 

Ruby 把 包 打 包 成 gem 格式 。Gemfile 是 清单 文件 ， 用 于 列 出 应 用 所 需 的 gem。 使 用 
Gemfile 文件 可 以 轻易 安装 所 需 的 全 部 库 : 在 shell 终端 里 执行 bundte 命令 即 可 。 这 个 命 
令 会 下 载 所 需 的 gem， 如 果 需 要 还 会 编译 源码 。 





























.Tuby-version 或 .TVmrc 

这 两 个 文件 告诉 应 用 (或 shell) 使 用 哪个 Ruby 版 本 。 除 了 指定 所 需 的 依赖 之 外 ， 应 用 
中 通常 还 会 有 这 个 文件 。 如 果 使 用 RVM， 它 会 切换 到 指定 的 Ruby 版 本 ， 或 者 提示 你 
安装 。 假 设 有 个 应 用 只 能 使 用 Ruby 2.1.3 运行 ,我们 可 以 创建 一 个 名 为 .ruby-version 的 
文件 ， 写 人 字符 串 ruby-2.1.3， 这 样 启动 应 用 时 会 自动 使 用 那个 Ruby 版 本 。 此 外 ， 其 
他 Ruby 工具 (如 无 需 配置 的 Web 服务 器 Pow) 也 会 读 取 .ruby-version 文件 ， 使 用 那里 
指定 的 Ruby 版 本 。 
































config.ru 

这 个 文件 的 作用 是 使 用 Rack 运行 Ruby 应 用 。Rack 是 Web 服务 器 接口 ， 兼 容 多 种 应 用 
服务 器 。 如 有 果 见 到 config.ru 文件 ， 说 明 应 用 可 以 使 用 多 个 不 同 的 服务 器 运行 ， 例 如 网 
上 很 多 大 型 网 站 在 生成 环境 中 使 用 的 前 端 服务 器 ， 或 者 一 台 笔记 本 电脑 中 运行 的 小 型 服 
务 器 。Rack 简化 了 服务 器 的 设置 。 























.1.3 安装 Ruby 的 过 程 中 可 能 遇 到 的 问题 

缺少 系统 工具 

如 果 使 用 Mac OS X， 需 要 安装 Xcode 和 命令 行 工 具 。 如 果 你 是 软件 开发 者 ， 这 些 可 
能 已 经 安装 好 了 。 如 果 没 有 ， 参 阅 在 线 文档 安装 。 如 果 使 用 Linux， 可 能 没有 安装 编 
译 器 。 使 用 这 个 命令 可 以 安装 全 部 可 能 用 到 的 构建 工具 : sudo apt-get instaLL build- 
essential。 这 个 命令 可 能 要 执行 一 会 儿 ， 不 过 会 把 构建 RVM 和 二 进 制 gem 所 需 的 工具 
都 安装 上 。 








缺少 开发 者 库 

有 些 支持 Ruby 的 库 (例如 readline， 其 作用 是 在 交互 式 Ruby shell 中 使 用 命令 行 历史 ) 
可 能 没有 安装 ， 或 者 对 RVM 不 可 用 。RVM 进步 很 多 了 ， 现 在 能 检测 有 没有 所 需 的 库 ， 
而 且 通 常会 告诉 你 如 何 正确 配置 这 些 库 。 使 用 RVM 安装 Ruby 时 ， 一 定 要 阅读 屏幕 上 
的 输出 ， 找 出 针对 所 在 平台 的 具体 说 明 。 
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B.2 积极 拥抱 NodeJS 的 GitHub 


NodeJS 是 服务 器 版 JavaScript。JavaScript 是 唯一 在 Web 客户 端 普遍 使 用 的 编程 语言 。 使 
用 Ruby 和 JavaScript 可 以 构建 任何 所 需 的 Web 应 用 。Hubot 这 样 的 工具 体现 了 使 用 运行 
在 NodeJS 平台 中 的 JavaScript 语言 构建 应 用 的 好 处 。 使 用 NodeJS 可 以 构建 “快速 且 可 弹 
性 伸缩 的 网 络 应 用 ”。 




















B.2.1 安装 NodeJS 
nodejs.org 网 站 提供 了 不 同 的 二 进 制 安装 程序 。 这 通常 是 安装 最 新 版 NodeJS 的 最 佳 方式 。 











al 


B.2.2 Node 版 本 管理 工具 

NVM 是 Node Version Manager 的 简称 ， 类 似 于 RVM。 与 RVM 一 样 ， 使 用 NVM 可 以 在 
一 台 设 备 中 安装 多 个 NodeJS 版 本 ， 而 且 可 以 在 不 同 的 版 本 之 间 无 颖 切换 。 这 对 快速 迭代 
的 NodeJS 来 说 (NodeJS 的 模块 通常 只 在 最 新 版 中 测试 ) 十 分 有 用 。NVM 可 以 运行 在 OS 
X 和 Linux 中 。 在 shell 终端 里 执行 下 述 命令 ,安装 NVM。 














$ curl -o- \ 
https://raw.githubusercontent.com/creationix/nvm/vO.25.3/install.sh | \ 
bash 


这 个 命令 会 安装 NVM。 安 装 好 之 后 ， 可 能 要 执行 source ~/.bash_profile， 加 载 相关 的 
NVM 脚本 。 然 后 ， 可 以 执行 NVM 命令 了 。 


$ nvm install 0.10 # 安装 0.10 版 
$ nvm use 0.10 # 使 用 0.10 版 





NVM 提供 了 很 多 命令 ， 详 情 参阅 它 的 仓库 (https://github.com/creationix/nvm ) 。 


B.2.3 package.json 


Ruby 使 用 Gemfile 指定 所 需 的 库 ，NodeJS 也 有 这 种 文件 。 在 NodeJS 中 ， 这 个 文件 是 
package.json。 为 了 安装 项 目 所 需 的 全 部 库 ， 要 使 用 npm 工 具 〈 使 用 NVM 安装 NodeJS 时 
会 自动 安装 npm)。 如 果 项 目 中 有 package.json 文件 ， 执 行 不 带 参 数 的 npn 命令 会 安装 指 
定 的 全 部 库 。 如 果 想 把 库 添加 到 现 有 的 package.json 文件 中 ， 可 以 在 npm 命令 后 面 加 上 
--save; 此 时 ，npm 把 库 安装 完 之 后 会 更 新 package.json 文件 。 
































B.3 命令 行 基础 知识 和 shell 


书 中 大 多 数 章节 (第 1 章 除 外 ) 都 只 关注 某 一 门 编程 语言 ， 可 是 所 有 章节 都 用 到 了 命令 
行 。shell 有 些 星 淮 难 懂 的 地 方 你 可 能 不 熟悉 ， 这 里 做 些 说 明 ， 再 附 些 示例 。 
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B.3.1 ”shell 注 释 
在 shell 命令 中 ，# 符 号 后 面 的 都 是 注释。 这 样 便于 在 同一 行 中 说 明 命 令 的 作用 : 























$ cat file.txt # 打印 file.txt 文 件 中 的 内 容 








这 个 命令 在 file.txt 字符 串 之 后 结束 。 本 附录 大 量 使 用 注释 说 明 shell 命令 的 作用 。 





B.3.2 为 命令 提供 变量 

shell 中 的 进程 在 一 个 环境 中 运行 ， 而 这 个 环境 可 以 使 用 键 值 对 配置 。 这 对 键 值 叫 作 环 境 变 
量 。 我 们 经 常 从 环境 变量 中 读 取 密码 ， 在 运行 时 使 用 ， 而 不 直接 在 源码 中 编写 密码 。 环 境 
变量 可 以 在 命令 前 面 使 用 等 号 连接 键 值 对 指定 ， 也 可 以 使 用 export 命令 导出 ， 供 多 个 命令 
使 用 : 























$ PASSNORD=MyPwd123 myProgram # 把 PASSWORD 变 量 的 值 提 供给 myProgram 
$ export PASSWORD=MyPwd123 
$ myProgram # 现在 PASSWORD 的 值 持久 可 用 


B.3.3 把 命令 分 成 多 行 
shell 命令 在 按 下 回 车 键 后 调用 。 不 过 ， 有 了 时 为 了 可 读 性 ， 想 把 命令 分 成 多 行 写 。 此 时 ， 可 
以 使 用 反 斜 线 分 隔 各 行 : 





$ git Log -S http 





上 述 命令 可 能 并 不 需要 分 成 多 行 ， 我 们 只 是 做 个 演示 。 这 个 示例 表明 ， 两 个 命令 的 作用 完 
全 一 样 。 


B.3.4 ”把 输出 传 给 后 续 命令 

shell 命令 大 都 出 现 得 很 早 ， 那 时 程序 由 多 个 小 功能 块 组 成 ， 这 与 现在 集成 多 项 功能 的 GUI 
程序 形成 鲜明 的 对 比 。 各 个 程序 通常 只 做 一 些 简 单 的 事情 ， 然 后 把 信息 传 给 另 一 个 程序 ， 
做 进一步 处 理 。 在 程序 之 间 传 递 数据 需要 一 种 优雅 的 方式 ， 因 此 管道 诞生 了 。 管 道 增进 了 
进程 之 间 的 通信 : 一 个 命令 的 输出 变 成 另 一 个 命令 的 输入 。 




















$ cat /etc/mime.types | grep http 
application/http 
application/vnd.httphone 
application/x-httpd-eruby rhtml 
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application/x-httpd-php 
phtml pht php 
application/x-httpd-php-source phps 


上 述 命 令 使 用 cat 程序 输出 /etc/mime.types 文件 中 的 内 容 ， 然 后 把 信息 传 给 grep 程序 ， 找 
出 文件 名 中 包含 字符 串 http 的 全 部 文件 。 





B.3.5” 重 定向 


类 似 于 管道 ，shell 还 支持 使 用 > 和 >> 符号 把 输出 重 定向 到 文件 中 。> 符号 覆盖 现 有 的 文件 
(如 果 文 件 不 存在 ， 新 建文 件 )， 而 >> 符号 把 内 容 添 加 到 文件 末尾 。 

















$ cat /etc/mime.types | grep http > saved-output.txt 


执行 上 述 命 令 之 后 ，saved-output.txt 文件 中 的 文本 与 前 面 的 管道 示例 输出 的 内 容 一 样 。 如 
果 这 个 文件 已 存在 ， 那 么 内 容 会 被 覆盖 。 
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Chris Dawson 的 父母 是 公立 学 校 的 教师 。Chris 从 小 就 对 电脑 十 分 着 迷 ， 但 在 学 习 和 教 
学 的 过 程 中 也 时 有 挫折 。 他 在 多 家 著名 的 创业 公司 和 科技 公司 (如 Apple、Virage 和 
RealNetworks) 默默 无 闻 地 工作 过 。 他 很 感激 有 机 会 在 三 个 大 洲 生 活 过 ， 让 他 感受 了 多 元 
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这 让 他 十 分 享受 。 





Ben Straub 立志 终身 做 一 名 开发 者 ， 他 热 表 于 开发 优秀 的 软件 。 他 编写 软件 15 年 了 ， 写 过 
多 本 书 ， 还 录制 过 软件 培训 教学 视频 。 他 热爱 阅读 ， 喜 欢 带 孩 子 骑 车 ， 喜 欢 巧 克 力 、 狗 、 
精致 的 笔记 本 ， 爱 好 摄影 、 在 周末 修改 程序 、 旅 游 、 写 作 、 做 饭 、 手 工 活 ， 醉 心 于 好 笔 、 
Markdown， 喜 欢 听 音 乐 、 看 电影 ， 还 喜欢 跟 优 秀 的 人 聊天 。 


土 
关于 封面 
本 书 封面 上 的 动物 是 小 猎犬 (beagle)， 一 种 中 小 体型 的 狗 〈 家 犬 ) 。 现 代 的 小 猎犬 品种 于 
19 世纪 30 年 代 在 大 不 列 颠 培育 ， 最 初 用 于 追踪 小 猎物 ， 如 免 子 。 因 此 ,在 狩猎 中 使 用 小 
猫 厂 追踪 猎物 就 叫 作 “beagling”。 





小 猎犬 属于 狗 这 个 品种 里 的 猎犬 科 ， 但 是 比 其 他 猎犬 体型 小 ， 而 且 腿 和 鼻子 较 短 。 小 猎犬 
身上 通常 有 三 种 颜色 (和 白 、 黑 和 棕 ) ， 不 过 偶尔 只 有 其 中 两 种 颜色 。 


小 猫 厂 是 备 受 喜爱 的 家 养 宠 物 ， 因 为 它们 性 格 温顺 ， 和 智商 高 。 自 伊 丽 水 白 时 代 起 ， 小 猫 三 
就 出 现在 大 众 文化 中 了 ， 在 莎士比亚 的 作品 和 现代 的 连环 漫画 中 都 有 出 现 。 


O’Reilly 出 版 的 图 书 ， 封 面 上 很 多 动物 都 濒临 灭绝 。 这 些 动物 都 是 地 球 的 至 宝 。 如 果 你 想 
知道 如 何 保护 这 些 动物 ， 请 访问 animals.oreilly.com。 


封面 图 片 出 自 Lydekker 的 Royal Natural History, Vol. 1。 
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OREILLY 





GitHub 实 践 


想 要 满足 独特 的 开发 需求 ? 那 就 在 下 一 个 项 目 中 使 用 GitHub 提 供 的 强大 
API 吧 ! 本 书 将 手把手 教 你 如 何 构建 软件 工具 ， 并 定制 属于 你 的 GitHub 工 
作 流 程 。 书 中 每 一 章 都 要 求 你 自己 动手 实践 ， 并 介绍 使 用 GitHub 提 供 的 
各 项 技术 时 应 采取 的 折 中 方案 以 及 注意 事项 。 


如 果 你 是 经 验 丰 富 的 程序 员 并 熟知 GitHub， 你 将 学 到 如 何 使 用 GitHub API 


及 相关 的 开源 技术 ， 如 Jekyll (网 站 生成 工具 ) 、Hubot (NodeJS 聊 天 机 
器 人 ) 和 Gollum (维基 ) 构建 工具 。 


本 书 主要 内 容 如 下 : 


国 使 用 Gist API 命 令 行 工具 和 Ruby 的 API 客 户 端 Octokit， 构 建 一 个 
简单 的 Ruby 服 务 器 


加 使 用 Gollum 命 令 行 工具 构建 一 个 图 像 管理 程序 
目 使 用 Python 构建 一 个 搜索 GitHub 的 GUI 工具 

目 说 明 第 三 方 工具 和 自己 编写 的 代码 如 何 交互 

目 使 用 GitHub 仓 库 中 的 数据 创建 完整 的 Jekyll 博 客 
罩 创建 一 个 Android 移 动 应 用 ， 读 写 Jekyll 仓 库 

加 在 GitHub 中 托管 一 个 完整 的 JavaScript 单 页 应 用 
加 使 用 Hubot 自 动 审查 拉 取 请 求 


Chris Dawson， 曾 就 职 于 Apple、Virage 和 RealNetworks 等 知名 IT 企业 ， 现 
于 eBay 工作 。 他 积极 参与 并 见证 了 GitHub 的 发 展 ， 自 己 也 开 了 一 家 公司 
Webiphany。 

Ben Straub，IT 服 务 公司 Gridium 的 开发 人 员 ， 热 衷 于 开发 优秀 的 软件 ， 最 
近 刚 加 入 GitHub。 除 写 过 多 本 书 之 外 ， 他 还 兼职 在 线 软件 开发 培训 。 
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这 本 书 能 带 你 入 门 并 精通 
GitHub API 的 用 法 。 不 管 你 使 
用 哪 门 编程 语言 ， 通 过 了 解 书 
中 使 用 GitHub API 开 发 的 多 个 
项 目 ， 你 都 能 立即 把 所 学 的 知 
识 运用 到 日 常 工作 中 。” 
一 一 Kyle Daigle 
GitHub 高 级 平台 工程 师 
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